Skip to main content
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.
The token already names the patient you searched for. Add 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 is open 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 new start 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:
A substitute shows up as a 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 422 with code slot_token.tampered.
  • Do not cache offers. Tokens live about five minutes. Read expires_at per 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_until and drops the offer once it passes. Booking directly stays allowed until expires_at.
  • It books only the patient you searched for. Reserving, booking and rescheduling take the patient from the token. A patient_id that differs from it is a 400 with code slot_token.patient_mismatch; a matching one is accepted. A token from a search without patient_id still needs patient_id when you reserve or book.
  • Nothing identifies the provider. The offer has no provider field, and it does not need one.
Pass render_in_timezone with the patient’s IANA zone and each offer gains display_start_at / display_end_at already rendered in that zone. start and end stay UTC, so you can display one and store the other.

Reservations

A reservation stops a slot being offered until it is confirmed or expires.
  • Reservations last about five minutes. expires_at on the response is authoritative.
  • Confirm by booking with the reservation_id. The patient, provider, and window all come from the reservation, so patient_id is not needed there.
  • Releasing is idempotent: an unknown, expired, or already-confirmed reservation_id all return 204. 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.
  • from and to bound 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_id and the window lifts entirely. One patient’s history is small enough to return whole.
  • limit sizes 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 a 400.
  • 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 a 400 (appointment_list.cursor_filter_mismatch) — the cursor seals the filter set, though not limit.

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:
That appointment was booked for the 18th, moved to the 20th, then cancelled — two items, because that is two operations. One item per operation, one entry per field it moved. The reschedule is one item whose 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_limit counts 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 moves start, end and sometimes provider_id per 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, keeping history=true set. A cursor sent without its flag is a 400, not a silent no-op. PATCH takes history and history_limit but 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.
If you want keys you can grep in your own logs, prefix the UUID rather than replace it — acme-appt_123-cancel-3f1c9e02-…. The UUID carries the uniqueness; the prefix is for you.
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.
The stored response is whatever the first request returned, including a failure. If your first attempt was rejected with a 400, retrying the corrected request under the same key replays that 400. The same applies to a 409: once a key has recorded a lost slot, it keeps returning that 409 while it is cached. Generate a new key whenever you change the request or search for a new slot, and reuse one only to repeat an identical attempt whose outcome you don’t know. Server errors (5xx) are not stored, so retrying after one is processed normally.

Errors

Scheduling returns the platform error shape, served as application/json:
Branch on 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 on error_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

A 409 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.
Reserving a slot before booking makes a 409 less likely. It does not remove the possibility — two callers can still race for the same reservation — but it shortens the exposed window to the moment of selection, rather than leaving it open for however long the patient spends confirming.
Do not retry a 409 with the same slot_token. That window is gone; the token cannot become valid again. Retrying with the same Idempotency-Key will replay the 409 rather than attempt a new booking — search again and use a new key.