Video-call 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	/video-call/livekit/appointment	201 Created
Update	PUT	/video-call/livekit/appointment/:appointmentId	200 OK
List appointments for the caller	GET	/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

curl --request POST \
  --url 'https://api.sandbox.ovok.com/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 and active-call notification operations when your flow needs them.

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

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

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/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 /video-call/livekit/mail/update separately.

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.

curl --get 'https://api.sandbox.ovok.com/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. 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

Status	Common cause
400	Invalid request body, date order, appointment id, or query; no valid user/project context; or no Practitioner is among the resolved participants.
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 or notifications and email.