OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Video Call

Create video call Appointment

  • Sandbox: available
  • Staging: available
  • Production: unknown
POST
/video-call/livekit/appointment

Creates a video call Appointment with its participants. Use it before you invite participants or create join links.

Auth: bearer token. The caller must be a Practitioner, an admin or a super admin, or hold the "System Owner" access policy. Scope: the caller's project (from the token). Participant accounts are looked up and created in that project.

Behaviour

  • start and end are UTC date-times. end must be later than start.
  • Participants are identified by email. Duplicate emails are dropped.
  • For each email, a Practitioner account in the project is used if one exists. Otherwise a Patient account is used, and one is created if the email has none yet.
  • The Appointment must have at least one Practitioner participant.
  • Each participant gets a TAN (a one-time access code), valid from one hour before the request until one day after end. Invitation and update emails include it.
  • The Appointment gets a random passphrase. Join links include it, and you cannot set or change it.
  • Participants are stored with status tentative. The route sends no emails and creates no access permission. Use POST /video-call/livekit/mail/invite to email participants and POST /video-call/livekit/notification/active-call/{appointmentId} to let them join.

Example

curl -X POST 'https://api.sandbox.ovok.com/video-call/livekit/appointment' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{    "start": "2026-01-01T12:00:00Z",    "end": "2026-01-02T12:00:00Z",    "comment": "Check-up call",    "description": "Follow-up appointment",    "videoCallParticipants": [{ "email": "max.mustermann@example.com" }]  }'

Authorization

bearer
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
id?string

Appointment ID.

start*string

Start date-time of the video call appointment. ATTENTION: Start date must be provided in UTC+0 (GMT+0) time.

Formatdate-time
end*string

End date-time of the video call appointment. ATTENTION: End date must be provided in UTC+0 (GMT+0) time.

Formatdate-time
comment*string

Title of the video call appointment.

Length1 <= length
description?string

Brief description of the video call appointment.

videoCallParticipants*array<>

Video call participants.

Items1 <= items

Response Body

Video Call Appointment created.

application/json
  1. response
id*string

Appointment ID.

resourceType?string

Appointment resource type.

Default"Appointment"
status*string

Appointment status.

Value in"proposed""pending""booked""arrived""fulfilled""cancelled""noshow""entered-in-error""checked-in""waitlist"
start*string

Start date-time of the video call appointment. ATTENTION: Start date is provided in UTC+0 (GMT+0) time.

Formatdate-time
end*string

End date-time of the video call appointment. ATTENTION: End date is provided in UTC+0 (GMT+0) time.

Formatdate-time
comment*string

Title of the video call appointment.

Length1 <= length
description?string

Brief description of the video call appointment.

videoCallParticipants*array<>
passphrase*string

Passphrase for the video call appointment.

Example Request
curl -X POST 'https://api.sandbox.ovok.com/video-call/livekit/appointment' \  -H 'Content-Type: application/json' \  -d '{  "start": "2019-08-24T14:15:22Z",  "end": "2019-08-24T14:15:22Z",  "comment": "string",  "videoCallParticipants": [    {      "email": "user@example.com"    }  ]}'
Example Response
{  "id": "string",  "resourceType": "Appointment",  "status": "proposed",  "start": "2019-08-24T14:15:22Z",  "end": "2019-08-24T14:15:22Z",  "comment": "string",  "description": "string",  "videoCallParticipants": [    {      "email": "user@example.com",      "status": "accepted",      "profileRef": "string"    }  ],  "passphrase": "string"}

Fetch user's video call Appointments GET

Lists the video call Appointments in which the signed-in user is a participant, ordered by date. **Auth:** bearer token. Any signed-in user can call it. **Scope:** the caller's project (from the token). Only Appointments that name the caller's own profile as a participant are returned. ## Behaviour - Only Appointments created through the video call routes are returned. - `startDate` and `endDate` are optional. Each is a UTC date-time such as `2025-01-01T14:00:00Z`, with an optional FHIR search prefix (`eq`, `ne`, `lt`, `gt`, `ge`, `le`, `sa`, `eb`, `ap`), for example `ge2025-01-01T00:00:00Z`. Each becomes a FHIR `date` search on the Appointment start. - The route has no paging. It returns every match in one response. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/video-call/livekit/appointment?startDate=ge2026-01-01T12:00:00Z&endDate=le2026-01-02T12:00:00Z' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Update video call Appointment PUT

Replaces the time, title, description and participants of an existing video call Appointment. Use it to reschedule a call or change who is invited. **Auth:** bearer token. The caller must be a Practitioner, an admin or a super admin, or hold the "System Owner" access policy. **Scope:** the caller's project (from the token). ## Behaviour - The Appointment is identified by the `appointmentId` path parameter. Any `id` in the body is ignored. - The body works like the create route: `end` must be later than `start`, participants are identified by email and deduplicated, and at least one must be a Practitioner. Unknown emails become Patient accounts. - The participant list is replaced by the one you send. Send everyone who should stay. - The passphrase of the Appointment does not change, so existing join links keep working. - New TANs are created for all participants on every update. - If the Appointment already has an access permission, its recipients are replaced by the new participant list. A Patient you add can therefore join without a second call to the active-call notification route. - The route sends no emails. Use `POST /video-call/livekit/mail/update` to tell participants about the change. ## Example ```bash curl -X PUT 'https://api.sandbox.ovok.com/video-call/livekit/appointment/c3499c27-2973-0a7f-807e-fb8676a92dcb' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "start": "2026-01-01T12:00:00Z", "end": "2026-01-02T12:00:00Z", "comment": "Check-up call", "videoCallParticipants": [{ "email": "max.mustermann@example.com" }] }' ```