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.
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:
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.
POST /v0.1/appointments.
Locked by check
reservations-need-slot-token-and-patient.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 anappointment_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
Before you build
GET /v0.1/appointment-typesreturns at least one typeGET /v0.1/slots?appointment_type_id=<id>&from=<iso>&to=<iso>returns availability- Your programs’ appointment types cover every visit kind you intend to offer
Related
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
