Skip to main content
Scheduling is the second leg of a staged rollout, after intake. The endpoints below are readable and bookable; whether your tenant has appointment types and provider availability configured is a separate question — check that first.

What you’ll do

1

List what can be booked

GET /v0.1/appointment-types — the bookable types for your tenant.
2

Find availability

GET /v0.1/slots with appointment_type_id, from and to, plus the patient_id.
3

Book it

POST /v0.1/appointments, then PATCH to reschedule or cancel.
4

Hold a slot when you need to

POST /v0.1/reservations with the slot’s slot_token.

The flow

Recipe 5.1 · What can be booked

GET /v0.1/appointment-types returns the bookable appointment types for your tenant.
An empty collection means none are configured yet. That is a provisioning matter — ask your OLH implementation contact to set up the appointment types for your programs.
Locked by check appointment-types-listable.

Recipe 5.2 · When is it available

GET /v0.1/slots — three parameters are required and the call returns 400 Invalid query parameters without them:
Pass state when your programs are licensure-limited — availability legitimately differs by state, and omitting it can show a patient a slot they cannot actually use.
Locked by check slots-requires-three-parameters.

Recipe 5.3 · Book, list and change an appointment

POST /v0.1/appointments creates the appointment. GET /v0.1/appointments lists them, filterable by patient_id, provider_id, appointment_type_id, status, outcome, from, to, timezone and sort.
Every one of those filters validates its input — an unrecognised value returns 400 rather than being ignored. That is the desirable behaviour, and it differs from the commerce endpoints; see API status.
Locked by check appointment-filters-validate.
PATCH /v0.1/appointments/{id} for a reschedule or a cancellation. Read the appointment back afterwards rather than assuming the patch applied as sent.

Recipe 5.4 · Hold a slot before you confirm

POST /v0.1/reservations holds a slot. It requires slot_token, from the slot you selected in the previous recipe. The token carries the patient your slot search named, so patient_id is needed only when that search did not send one; a patient_id that differs from the token’s is a 400 (slot_token.patient_mismatch). DELETE /v0.1/reservations/{id} releases the hold.
Use it when there is a gap between the patient choosing a time and confirming — otherwise you race another booking between your availability read and your POST /v0.1/appointments.
Locked by check reservations-need-slot-token-and-patient.
A GET on /v0.1/reservations returns a 403 naming the Authorization header while a POST on the same path is routed — it reaches validation and returns 400 naming slot_token. That shape of 403 is a wrong-method signal, not a permission problem — see Getting started for the three 403s and what each one means.
Locked by check authorization-403-is-usually-a-wrong-method.

What comes back

An empty items array on appointment types or slots is a provisioning answer, not a shape problem — see Gotchas.

How appointments relate to the rest of the journey

An encounter carries an appointment_ids array, so an appointment can be associated with the clinical encounter. In tenants we have tested, that array is empty — so do not build logic that depends on it until you have confirmed it is populated for yours.

Gotchas

Scheduling is configured per tenant. If GET /v0.1/appointment-types or GET /v0.1/slots comes back empty, scheduling is not configured for your tenant yet and no amount of client code will change that. Ask for it rather than debugging your request.

Before you build

  1. GET /v0.1/appointment-types returns at least one type
  2. GET /v0.1/slots?appointment_type_id=<id>&from=<iso>&to=<iso> returns availability
  3. Your programs’ appointment types cover every visit kind you intend to offer

Order status and tracking

The leg before this one: order status, items and tracking

Refills

The next leg: a refill is a questionnaire; the clinician prescribes and you read the new order

Retries and idempotency

When a booking times out: the two appointment writes that require an Idempotency-Key