> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduling

> Search provider availability, reserve a slot, book an appointment, and manage its lifecycle.

> [!NOTE]
>
> See [Appointments and scheduling](https://openloop.mintlify.site/cookbook/appointments-and-scheduling.md) 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.

```bash theme={null}
curl -G 'https://api.openloophealth.com/v0.1/slots' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'appointment_type_id=8f2c6c1e-4b1a-4c73-9f65-2b0c9a7d5e41' \
  --data-urlencode 'from=2026-08-18T00:00:00Z' \
  --data-urlencode 'to=2026-08-25T00:00:00Z' \
  --data-urlencode 'patient_id=3c9a1e42-7b6d-4f1a-9c2e-1d5b7a8e4f3c' \
  --data-urlencode 'state=CA' \
  --data-urlencode 'render_in_timezone=America/Los_Angeles'
```

> [!TIP]
>
> 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`.

```bash theme={null}
curl -X POST 'https://api.openloophealth.com/v0.1/appointments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3d1c94-1a1e-4a2f-bb2e-6e1f0f2a9c55' \
  -d '{
    "slot_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..."
  }'
```

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.

> [!TIP]
>
> 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`).

| Arm | Body | What it does |
| - | - | - |
| `cancel` | `{ "cancel": { "reason": "patient moved" } }` | Closes with outcome `cancelled` and frees the slot. `reason` is optional — `{ "cancel": {} }` is a valid cancel |
| `reschedule` | `{ "reschedule": { "slot_token": "..." } }` | Moves it to the window the token seals. Same appointment id |
| `complete` | `{ "complete": {} }` or `{ "complete": { "no_show": true } }` | Closes with outcome `completed`, or `no_show` when the patient did not attend |
| `reopen` | `{ "reopen": {} }` | Re-opens a closed appointment, whatever outcome closed it |

```bash theme={null}
curl -X PATCH 'https://api.openloophealth.com/v0.1/appointments/1c7e9b40-5f2a-4d18-9d3e-8a4c2f6b1e07' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 9a2b7c31-4e5f-4a90-8c11-2d6e3f7b8a04' \
  -d '{ "complete": { "no_show": true } }'
```

`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:

| What happened | How you tell | What to tell the patient |
| - | - | - |
| The original window was still free | `status` is `open` and `provider_id` is unchanged | The original appointment is back |
| Another provider took the window | `status` is `open` and `provider_id` differs | Same time, different provider |
| Nobody could take the window | `status` stays `closed`; `outcome` is `unresolved` | The appointment is still closed — offer a new time |

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:

```bash theme={null}
curl -X PATCH 'https://api.openloophealth.com/v0.1/appointments/1c7e9b40-5f2a-4d18-9d3e-8a4c2f6b1e07?history=true' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"reopen": {}}'
```

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.

> [!NOTE]
>
> 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.

> [!TIP]
>
> 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:

| What you send | How it is read |
| - | - |
| `from=2026-08-11&to=2026-08-11&timezone=America/Los_Angeles` | Exactly that Pacific day |
| `from=2026-08-11T00:00:00Z` | That instant, UTC |
| `from=2026-08-11T00:00:00-07:00` | That instant, Pacific |
| `from=2026-08-11` with no `timezone` | **Rejected** — `appointment_list.timezone_required` |
| `from=2026-08-11T00:00:00` | **Rejected** — `appointment_list.offset_required` |

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.

> [!NOTE]
>
> 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:

```bash theme={null}
curl -G 'https://api.openloophealth.com/v0.1/appointments/1c7e9b40-5f2a-4d18-9d3e-8a4c2f6b1e07' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'history=true' \
  --data-urlencode 'history_limit=25'
```

```json theme={null}
{
  "data": {
    "id": "1c7e9b40-5f2a-4d18-9d3e-8a4c2f6b1e07",
    "status": "closed",
    "outcome": "cancelled",
    "start": "2026-08-20T17:00:00Z",
    "end": "2026-08-20T17:30:00Z",
    "history": {
      "items": [
        {
          "id": "9a3f61d8-52c7-4e0b-8d14-6f2b9c7e3a05",
          "at": "2026-08-17T09:12:03Z",
          "source": "partner-api",
          "changes": [
            {
              "field": "start",
              "previous": "2026-08-18T15:00:00.000Z",
              "next": "2026-08-20T17:00:00.000Z"
            },
            {
              "field": "end",
              "previous": "2026-08-18T15:30:00.000Z",
              "next": "2026-08-20T17:30:00.000Z"
            }
          ]
        },
        {
          "id": "b1d0c6f2-30a4-4a8f-9d1b-7c5e2f0a9b31",
          "at": "2026-08-19T11:41:27Z",
          "source": "partner-api",
          "reason": "patient moved",
          "changes": [
            { "field": "status", "previous": "open", "next": "closed" },
            { "field": "outcome", "previous": null, "next": "cancelled" }
          ]
        }
      ]
    }
  },
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

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.

> [!TIP]
>
> 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.

> [!WARNING]
>
> 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`:

```json theme={null}
{
  "error": {
    "message": "Search window exceeds the 30-day maximum.",
    "error_code": "slot_search.window_too_large"
  },
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

**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 }`.

| Status | `error_code` | What to do |
| - | - | - |
| 400 | `slot_search.window_too_large` | Narrow the search window to 30 days or less |
| 400 | `slot_search.window_invalid` | `from` must precede `to` |
| 400 | `slot_search.state_required` | The type has `requires_state_license` — send `state` |
| 400 | `appointment_list.offset_required` | Add an explicit UTC offset to the timestamp |
| 400 | `appointment_list.timezone_required` | A bare date needs `timezone` |
| 400 | `appointment_list.window_too_large` | Narrow the window to 31 days or less |
| 400 | `appointment_list.cursor_filter_mismatch` | The cursor was issued for different filters — restart the walk without one |
| 400 | `*.cursor_invalid` | The cursor could not be decoded — restart the walk without one, and check nothing is mangling it in transit |
| 400 | `missing-idempotency-key` | Add the `Idempotency-Key` header |
| 400 | `empty-patch` | The update body names no change — send one of the four arms |
| 400 | `conflicting-patch` | The update body names two changes — send one per request |
| 400 | `slot_token.expired` | The offer lapsed; search again for a fresh token |
| 400 | `slot_token.patient_mismatch` | The token was searched for a different patient — drop `patient_id`, or search again for this patient |
| 400 | `appointment.notes-invalid-html` | `notes` is plain text — strip `<` and `>` |
| 404 | `slot_search.appointment_type_not_found` | The type has no bookable slots configured |
| 404 | `patient.not_found` | The patient is not one your organization manages, or does not exist |
| 409 | `appointment.slot_unavailable` | The slot was claimed between your search and your booking |
| 409 | `appointment.invalid-state` | The appointment cannot make that transition — read its `status` and `outcome` first |
| 409 | `appointment.reschedule-conflict` | Every eligible provider's new slot is gone; search again |
| 409 | `reservation.reservation_expired` | The hold lapsed; search and reserve again |
| 422 | `slot_token.tampered` | The token was altered in transit; search again |
| 500 | `internal_error` | The write did not land. Nothing changed, so retry — see below |
| 500 | `internal.error` | Something else failed, possibly **after** the write landed. Re-read the appointment; do not retry the write |

### Handling 500

**Branch on `error_code`, not on the status.** Two different `500`s 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.

> [!TIP]
>
> 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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.