# Video-call appointments

Canonical page: https://docs.ovok.com/video-calls/appointments

Ovok represents each video call as a FHIR `Appointment`. The video-call routes return a purpose-built response with the appointment details and participants, rather than the full FHIR resource.

| Operation | Method | Path | Success |
| --- | --- | --- | --- |
| Create | `POST` | `/v1/video-call/livekit/appointment` | `201 Created` |
| Update | `PUT` | `/v1/video-call/livekit/appointment/:appointmentId` | `200 OK` |
| List appointments for the caller | `GET` | `/v1/video-call/livekit/appointment` | `200 OK` |

All three routes require a bearer token. Creating and updating require a Practitioner, project admin, super admin, or a caller with the **System Owner** access policy. Listing requires a signed-in profile and returns only appointments that include that profile.

## Create an appointment [#create-an-appointment]

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/video-call/livekit/appointment' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2026-10-12T09:00:00Z",
    "end": "2026-10-12T09:30:00Z",
    "comment": "Remote monitoring check-in",
    "description": "Review the latest home measurements",
    "videoCallParticipants": [
      { "email": "clinician@example.org" },
      { "email": "patient@example.org" }
    ]
  }'
```

| Request field | Required | Description |
| --- | --- | --- |
| `start` | Yes | UTC date-time in ISO format, such as `2026-10-12T09:00:00Z`. |
| `end` | Yes | UTC date-time later than `start`. |
| `comment` | Yes | Appointment title. Must not be empty. |
| `description` | No | Short description shown with the appointment. |
| `videoCallParticipants` | Yes | At least one participant object. |
| `videoCallParticipants[].email` | Yes | Valid participant email. Duplicate email addresses are removed. |

Ovok resolves participant accounts in the token's project. If an email belongs to a Practitioner account, that profile is used. Otherwise Ovok looks up a Patient and creates a Patient account if no matching account exists. At least one resolved participant must be a Practitioner.

The route creates the `Appointment` and participant TAN records. It does **not** send email or create the call's `CommunicationRequest` access grant. Use the separate [invitation email](/video-calls/notifications-and-email#send-an-invitation) and [active-call notification](/video-calls/notifications-and-email#start-the-call-and-notify-participants) operations when your flow needs them.

## Successful response [#successful-response]

| Response field | Meaning |
| --- | --- |
| `id` | FHIR `Appointment` id. Use it in update, access, notification, and email routes. |
| `resourceType` | `Appointment`. |
| `status` | FHIR appointment status. Ovok creates the appointment with `booked`. |
| `start`, `end` | Appointment start and end in UTC. |
| `comment` | Appointment title. |
| `description` | Optional description. |
| `videoCallParticipants[]` | Resolved participants, with `email`, FHIR `profileRef` such as `Patient/<id>` or `Practitioner/<id>`, and participant status. Ovok stores new participants with status `tentative`. |
| `passphrase` | Appointment's generated passphrase. Ovok creates it and preserves it when the appointment is updated. |

The FHIR resource is marked as a video-call appointment with a dedicated identifier. The passphrase is stored in an Ovok extension on the `Appointment`.

## Update an appointment [#update-an-appointment]

The `appointmentId` in the path identifies the FHIR resource. Send the same fields as create; `videoCallParticipants` is the replacement participant list.

```bash
curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/video-call/livekit/appointment/2d5d6f7e-1184-4b4f-a4fc-12b50792ed0d' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2026-10-12T09:30:00Z",
    "end": "2026-10-12T10:00:00Z",
    "comment": "Remote monitoring check-in",
    "description": "Rescheduled review of home measurements",
    "videoCallParticipants": [
      { "email": "clinician@example.org" },
      { "email": "patient@example.org" }
    ]
  }'
```

Updating keeps the appointment id and passphrase, refreshes participant TAN records, and replaces the participant list. If the appointment already has an access grant, Ovok updates that grant's recipients to match the new list. It does not send update emails; call [`POST /v1/video-call/livekit/mail/update`](/video-calls/notifications-and-email#send-an-update) separately.

## List my appointments [#list-my-appointments]

The list is restricted to appointments that include the signed-in user's own profile. Results are ordered by appointment date. `startDate` and `endDate` are optional FHIR `date` search values; they accept an ISO UTC date-time and an optional FHIR prefix such as `ge` or `le`.

```bash
curl --get 'https://api.sandbox.ovok.com/v1/video-call/livekit/appointment' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode 'startDate=ge2026-10-01T00:00:00Z' \
  --data-urlencode 'endDate=le2026-10-31T23:59:59Z'
```

The response is an array using the [appointment response fields](#successful-response). The API follows FHIR search pages internally and returns the matching results in that array; there is no separate page cursor in this route's response.

## Errors to account for [#errors-to-account-for]

| Status | Common cause |
| --- | --- |
| `400` | No valid user or project context, the project cannot be found, `start` is not before `end`, no Practitioner of the project is among the participants, or the appointment cannot be created, found or read. |
| `422` | The body, the `appointmentId` or a query parameter fails validation. `errors` names each invalid field. |
| `401` | Missing or invalid bearer token. |
| `403` | Caller lacks the required Practitioner, admin, super-admin, or **System Owner** access. Applies to create and update. |
| `404` | The project client application or requested appointment cannot be found. |

Continue with [join access](/video-calls/join-access) or [notifications and email](/video-calls/notifications-and-email).
