Video calls

Ovok's video-call API connects an FHIR Appointment to a LiveKit room. Your application creates the appointment, tells participants when the call is ready, and requests a join token for each person who enters the room.

The API separates those steps. Creating an appointment does not send email or grant Patient access. Starting a call creates the access grant and queues a real-time notification. Join-access endpoints then issue the room URL and token.

Typical workflow

1. Create an appointment with at least one Practitioner participant. Ovok resolves each participant by email within the project; an address without a Practitioner account is looked up as a Patient and a Patient account is created when needed.
2. Send invitation emails with the mail API if your workflow uses email. The appointment endpoint does not send them automatically.
3. When the Practitioner starts the call, send the active-call notification. This creates or replaces the appointment's access CommunicationRequest and queues an event for participants who are not already in the room.
4. Request join access for each signed-in participant, or have a Practitioner request guest access for someone without an Ovok account.
5. If appointment details change, update the appointment and send an update email separately. The cancellation mail endpoint sends a cancellation message; it does not cancel the FHIR Appointment.

Routes

All routes require a bearer token. The caller's project comes from that token.

Operation	Method	Path	Details
Create appointment	POST	/video-call/livekit/appointment	Appointments
Update appointment	PUT	/video-call/livekit/appointment/:appointmentId	Appointments
List my appointments	GET	/video-call/livekit/appointment	Appointments
Create guest access	POST	/video-call/livekit/guest-access/:appointmentId	Join access
Create signed-in user access	POST	/video-call/livekit/user-access/:appointmentId	Join access
Read my access grant	GET	/video-call/livekit/access-permission/:appointmentId	Join access
Notify participants that the call is active	POST	/video-call/livekit/notification/active-call/:appointmentId	Notifications and email
Send invitation email	POST	/video-call/livekit/mail/invite	Notifications and email
Send appointment update email	POST	/video-call/livekit/mail/update	Notifications and email
Send cancellation email	POST	/video-call/livekit/mail/cancel	Notifications and email

Path note: these controller routes are currently unversioned. Use the paths shown above; do not add /v1.

Authorization at a glance

Route group	Who can call it
Create, update, active-call notification, and mail	Practitioner, project admin, super admin, or a user with the System Owner access policy.
List appointments	Any signed-in user with a profile. Results are limited to appointments that include that user's profile.
Guest access	A signed-in Practitioner. This route checks the caller's profile type directly.
Signed-in user access	Practitioner or Patient. A Patient must have an access grant for the appointment. RelatedPerson is refused.
Read access grant	Signed-in user whose profile is one of the grant's recipients.

Before you integrate

• Your Ovok deployment must have its LiveKit service configured before it can issue join access.
• Email routes need the three video-call templates mapped and ready: VIDEO_CALL_APPOINTMENT_INVITE, VIDEO_CALL_APPOINTMENT_UPDATE, and VIDEO_CALL_APPOINTMENT_CANCEL. See setting up email and mapping templates.
• Appointment start and end values are UTC ISO date-times. The API rejects an end time that is not later than the start time.
• Treat videoCallUrl, livekitJwt, and the appointment passphrase as access credentials. Return them only to the intended participant.

Pages in this section

• Appointments — create, update, and list video-call appointments.
• Join access — issue room access for a guest or a signed-in Practitioner or Patient.
• Notifications and email — grant access when a call starts and message participants.