---
search:
  tags:
    - Appointments
    - POST
seo:
  description: >-
    Creates a new scheduled appointment. Automatically handles health plan
    management. Reference for the POST /appointments endpoint in the Almendra
    API.
sidebar:
  label: Create a scheduled appointment
  badge: POST
title: Create a scheduled appointment
type: openapi-operation
---
Creates a new scheduled appointment. Automatically handles health plan management.

Requires the `appointments:write` permission.

`POST /appointments`

**Request body** (`application/json`)

- `patient_id` (string, required) — Patient ID
- `scheduledTimeStart` (string<date-time>, required) — Appointment start time in ISO 8601 format
- `scheduledTimeEnd` (string<date-time>, required) — Appointment end time in ISO 8601 format
- `scheduledTimeDuration` (integer, required) — Appointment duration in minutes
- `location` (string) — Physical location of the appointment
- `conferenceType` (string) — Type of video conference
- `conferenceRoomUrl` (string<uri>) — Video conference URL
- `modality` (string, required) — Appointment modality
- `address` (string) — Address for home visit appointments
- `healthPlan_id` (string, required) — Health Plan ID
- `purchasedHealthPlan_id` (string) — Purchased Health Plan ID (if using existing plan)
- `price` (number, required) — Appointment price

Request body example:

```json
{
  "patient_id": "507f1f77bcf86cd799439011",
  "scheduledTimeStart": "2024-02-01T10:00:00.000Z",
  "scheduledTimeEnd": "2024-02-01T11:00:00.000Z",
  "scheduledTimeDuration": 60,
  "location": "Clinic Room 101",
  "conferenceType": "zoom",
  "conferenceRoomUrl": "https://zoom.us/j/1234567890",
  "modality": "Virtual",
  "address": "123 Main St, City, State 12345",
  "healthPlan_id": "507f1f77bcf86cd799439013",
  "purchasedHealthPlan_id": "507f1f77bcf86cd799439014",
  "price": 100
}
```

**Responses**

- `201` — Appointment created successfully
- `400` — Bad request - Invalid input
- `401` — Unauthorized - Invalid API key
- `403` — The account behind the API key has no active paid plan, or the key lacks the permission this operation needs
- `404` — Expert or patient not found
- `415` — Unsupported Media Type - send the body as JSON with Content-Type: application/json
- `429` — Rate limit exceeded (600 requests per 60 seconds); retry after \`Retry-After\` seconds
- `500` — Unexpected server error

Response example, 201:

```json
{
  "_id": "507f1f77bcf86cd799439016",
  "patient": "507f1f77bcf86cd799439011",
  "expert": "507f1f77bcf86cd799439012",
  "appointmentStatus": 0,
  "scheduledInfo": {
    "wasScheduled": true,
    "scheduledTimeStart": "2024-02-01T10:00:00.000Z",
    "scheduledTimeEnd": "2024-02-01T11:00:00.000Z",
    "scheduledDuration": 60
  },
  "location": "string",
  "conferenceType": "string",
  "conferenceRoomUrl": "string",
  "conferenceRoomId": "string",
  "price": 0,
  "purchasedHealthPlan": "string",
  "createdAt": "2024-01-15T00:00:00.000Z",
  "updatedAt": "2024-01-15T00:00:00.000Z"
}
```