See Appointments and scheduling in the Partner Cookbook for a staged, staging-verified walkthrough, including how to tell whether scheduling is provisioned for your tenant before you build against it.
Overview
Scheduling turns provider availability into bookable offers. You search for slots against an appointment type, get back opaque slot tokens, and hand one back to create the appointment. OpenLoop assigns the provider. That last part is the design: you never name a provider, and a slot offer carries no provider identity. Eligibility — state licensure and the appointment type’s own rules — is resolved while the search runs, so any offer you receive is one a real provider can serve.The flow
1
Find what you can book
Call
GET /v0.1/appointment-types to get the types your organization has adopted.GET /v0.1/appointment-types returned 200 with an empty items array on this tenant (2026-09-11). An empty list carries no signal about why it is empty.Retrieve a type to read its rules. requires_state_license is the one to check before searching: when it is true, your slot search must name the state the visit takes place in.2
Search availability
Call
GET /v0.1/slots with the appointment_type_id and a window. Windows may span at most 30 days.Send patient_id too. It is optional today and will become required. When you send it, a patient your organization does not manage is a 404 (patient.not_found), and every offer’s slot_token carries that patient, so you don’t send patient_id again when you reserve or book.Every offer carries a
slot_token and two deadlines. expires_at is the last moment the offer can be booked; reservable_until is the last moment it can be reserved. Check both against the current time before you display an offer, and drop one whose deadline has passed rather than letting the patient pick a time that will fail on submit.3
Reserve the slot, if your flow needs it
Optional.
POST /v0.1/reservations stops the slot being offered while the patient finishes the flow.This is worth doing whenever a step sits between slot selection and appointment creation — a confirmation page showing the time the patient picked, say, with a button they still have to press. Reserving the slot means that time is still available when they do. The provider is not yours to show yet: it is assigned when you book.Release the reservation if the patient abandons the flow — back button, reload, navigating away — rather than waiting out its expiry.4
Book
POST /v0.1/appointments with exactly one of slot_token or reservation_id. Send an Idempotency-Key.patient_id (the id POST /patients returned) only if your search did not send one.A
201 returns the created appointment, including its id and the provider_id assigned to it. Store the id — every later read and update keys on it.5
Manage the appointment
Read it with
GET /v0.1/appointments/{id}, or list a window with GET /v0.1/appointments. Every change — cancel, reschedule, complete, reopen — goes through one PATCH /v0.1/appointments/{id}.Both histories come from the retrieve call, as opt-in sub-objects rather than endpoints of their own.The appointment lifecycle
An appointment isopen or closed. PATCH /v0.1/appointments/{id} moves it, and the body names exactly one change per request. Two named changes is a 400 (conflicting-patch); none is a 400 (empty-patch).
complete settles the outcome in one call rather than two, because closing an appointment out and saying whether the patient turned up is one decision, not two.
Reschedule takes a token, not a time
There is no way to send a newstart and end. Search slots again, take a slot_token for the new time, and send that. The token is what proves the window is bookable, and the provider is re-selected from the set it seals — so a reschedule may land you a different provider than the original booking. The appointment id does not change, so your stored references stay valid.
Reopening is best-effort
Cancelling frees the slot, so reopening cannot promise the time back. Like every other arm, it returns the appointment — read what happened off it:
Comparing
provider_id needs the value you held before the call. If you don’t have one — reopening by id from a queue or a webhook, without reading the appointment first — ask the same call for the history and read the swap out of it:
provider_id entry naming both clinicians, in the same item as the status move that reopened it; the original coming back writes no such entry. You get the newest page — the one holding the change you just made — and on an Idempotency-Key replay you get the page stored at first execution rather than a fresh read. Older changes are reachable by paging backwards from GET /v0.1/appointments/{id} with the before cursor the embed returns.
On unresolved the appointment stays closed, but its outcome becomes unresolved rather than the one you disputed. Both reschedule and cancel work from there, so a disputed no-show does not strand the record.
Every arm is attributed to the subject of the access token you sent, recorded in scheduling’s own audit trail. What the history exposes is
source — partner-api for anything you send — so a provider UI and a patient app sharing one credential are indistinguishable there. Keep your own record if you need to tell them apart.Slot tokens
A slot token is opaque, self-contained, and integrity-protected. It seals the appointment type, the eligible providers, the window, and the patient when the search named one, and booking verifies that seal.- Pass it back verbatim. Do not parse it, build one, or edit one. A tampered token is a
422with codeslot_token.tampered. - Do not cache offers. Tokens live about five minutes. Read
expires_atper offer rather than assuming a duration, and search again instead of holding a list. - Watch the right deadline. A reserve-first flow counts down to
reservable_untiland drops the offer once it passes. Booking directly stays allowed untilexpires_at. - It books only the patient you searched for. Reserving, booking and rescheduling take the patient from the token. A
patient_idthat differs from it is a400with codeslot_token.patient_mismatch; a matching one is accepted. A token from a search withoutpatient_idstill needspatient_idwhen you reserve or book. - Nothing identifies the provider. The offer has no provider field, and it does not need one.
Reservations
A reservation stops a slot being offered until it is confirmed or expires.- Reservations last about five minutes.
expires_aton the response is authoritative. - Confirm by booking with the
reservation_id. The patient, provider, and window all come from the reservation, sopatient_idis not needed there. - Releasing is idempotent: an unknown, expired, or already-confirmed
reservation_idall return204. Fire it on abandonment without tracking whether the reservation is still live.
Reading appointments
Every appointment list is anchored or windowed, so no query can walk your whole history.fromandtobound the appointment’s start, not its end, as a half-open interval. A visit starting 23:55 Tuesday belongs to Tuesday.- Send no window and a recent one applies: 7 days back through 24 days out. An explicit window may span at most 31 days — a calendar month in one request.
- Send
patient_idand the window lifts entirely. One patient’s history is small enough to return whole. limitsizes the page — default 25, clamped at 100 (50 on/slots, where each page mints a token per offer). An over-large ask is clamped, not rejected; a non-positive one is a400.- Page until a response has no
after, not until a page comes back short. A full page can be the last one and a short page can be followed by another, so a walk that stops on a short page silently misses rows. Replaying a cursor under different filters is a400(appointment_list.cursor_filter_mismatch) — the cursor seals the filter set, though notlimit.
Every bound must name its zone
Each bound is resolved according to its shape:
An offsetless timestamp is rejected rather than assigned a zone: it has no single meaning, and resolving it server-side would shift a Pacific caller’s window by 7–8 hours without saying so.
A bare date resolves differently per bound: as
from it means the start of that local day, and as to it means through the end of it. from=to therefore returns exactly one day.
Send what the browser reports:
Intl.DateTimeFormat().resolvedOptions().timeZone. Abbreviations like PST are not IANA zone ids and are rejected.Appointment history comes from the retrieve call
One history sits behind an appointment, covering every field that has changed — the lifecycle (status, outcome) and the rest (start, end, provider_id)
alike. It has no endpoint of its own; you ask the retrieve call for it:
changes carries start and end; the cancel is one item carrying
status and outcome. Do not read the entries as separate events — a reschedule
that also re-picked the clinician is one item of three, not three changes. And do
not index into changes positionally: the entries of an item have no guaranteed
order.
previous and next are strings whatever the field is, because the log is
field-agnostic — a timestamp for start and end, a provider id for
provider_id, an enum value for status and outcome.
at, source and reason describe the operation, so they sit on the item
rather than repeating per entry. reason is present only when the change carried
one, such as a cancel.
provider_id appears here too. A reschedule re-selects the clinician from the
token’s eligible set, and a reopen may hand the window to a substitute, so either
can move the provider — and each records who held it and who holds it now, in the
same item as the status move that caused it.
- Omit the flag and the history is not read. A page that does not show it costs one request and nothing extra.
history_limitcounts ITEMS — one per operation — not the field entries inside them. A page of 25 is 25 operations, and can carry far more entries than that: an appointment whose history is mostly reschedules movesstart,endand sometimesprovider_idper item. Pages never split an item, which is the same fact stated from the other side — the page boundary IS an item boundary.- Page with
history_cursor, keepinghistory=trueset. A cursor sent without its flag is a400, not a silent no-op.PATCHtakeshistoryandhistory_limitbut no cursor: a mutation has no page to continue from.
Idempotency
POST /v0.1/appointments and PATCH /v0.1/appointments/{id} each require an Idempotency-Key header. Omitting one is a 400 with code missing-idempotency-key. Reservations do not take the header — a hold is cheap to repeat and expires on its own.
Why it exists. These calls are not repeatable: booking creates an appointment and claims a provider’s window. If a request times out you cannot tell from the client whether it succeeded, and a blind retry risks booking the patient twice or returning a 409 you have no way to interpret. The key resolves that ambiguity — a retry returns the original outcome instead of attempting a second write.
What to send. A UUID your client generates, one per attempt. Mint it when the user commits to the action — the moment they click Confirm — rather than when the HTTP call goes out, and hold it with that request’s state so every retry of that one click sends the same value. A new click is a new attempt and needs a new key.
One key per action, never per resource. A key is global to your integration: it is not scoped to an endpoint, to an appointment, or to a PATCH arm. So a key derived from the resource — appt_<id>, or a counter kept per patient — breaks on the second action against that resource. Book under appt_123, cancel later under appt_123, and the cancel replays the booking response: a 200, an appointment that looks untouched, and no write. Nothing rejects the reuse, because from the server’s side that is a retry. Give each of the four PATCH arms its own key for the same reason.
What a retry does. The first request under a key is processed normally and its response is stored for 24 hours. A later request under the same key skips processing and returns the stored response with x-idempotency-replayed: true added — so you get the original appointment id back, not a second appointment.
Errors
Scheduling returns the platform error shape, served asapplication/json:
error.error_code. It is a stable identifier; error.message is prose and may be reworded. Field-level validation failures add error.details, an array of { field, code, message }.
Handling 500
Branch onerror_code, not on the status. Two different 500s mean
opposite things, and the safe action differs.
internal_error (underscore) is the update arms’ own answer to a write that did
not land. Every arm answers alike, and the change rolls back whole — the
appointment, its history entry and the event it emits either all persist or none
do. Nothing is partially applied, so a retry is safe: 5xx responses are not
stored against your Idempotency-Key, so the retry runs as a fresh attempt
rather than replaying the failure.
internal.error (dot) is the catch-all for an unhandled failure, and it carries
no such guarantee. Some of those happen after the write has committed — asking
for history=true makes the response body do more work once the change is
already durable, and a failure there answers 500 on an update that succeeded.
Re-read the appointment before acting. Retrying that write can apply a second
change, or come back as a 409 appointment.invalid-state because the first one
already took effect.
Handling 409
A409 on booking or rescheduling means the window was claimed between your search and your call. It is expected under concurrency, not a bug: search again and offer the patient a fresh slot.
On the other update arms a 409 is appointment.invalid-state: the appointment cannot make that transition. Completing one that is already closed, or reopening one that is already open, both land here. Read the appointment’s status and outcome before offering the action.

