> ## 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.

# Appointments and scheduling

> What can be booked, when it is available, how to book and change a visit, and how appointments relate to intake and orders.

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

```mermaid theme={null}
flowchart LR
    A["GET /v0.1/appointment-types<br/>What can be booked"] --> B["GET /v0.1/slots<br/>When is it available"]
    B --> C["POST /v0.1/appointments<br/>Book it"]
    C --> D["PATCH /v0.1/appointments/:id<br/>Reschedule or cancel"]
```

## Recipe 5.1 · What can be booked

`GET /v0.1/appointment-types` returns the bookable appointment types for your tenant.

```bash curl theme={null}
curl "https://api-staging.openloophealth.com/v0.1/appointment-types" \
  -H "authorization: Bearer $TOKEN"
```

```json Response theme={null}
{ "items": [ { "id": "<appointment type id>", "name": "...", "duration_minutes": 20 } ],
  "request_id": "..." }
```

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.

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

| Parameter | Required | Notes |
| - | - | - |
| `appointment_type_id` | **Yes** | From the previous recipe |
| `from`, `to` | **Yes** | The window to search |
| `state` | No | Patient's state, for licensure-limited availability |
| `patient_id` | No, but send it | Will become required. Checked against your organization (`404 patient.not_found`), and carried in each `slot_token` so reserving and booking don't need it again |
| `render_in_timezone` | No | Return times in the patient's timezone rather than the default |
| `cursor`, `limit` | No | Pagination |

```bash curl theme={null}
curl "https://api-staging.openloophealth.com/v0.1/slots?appointment_type_id=<id>&from=<iso>&to=<iso>" \
  -H "authorization: Bearer $TOKEN"
```

```json Response theme={null}
{ "items": [ { "slot_token": "<opaque>", "start_at": "...", "end_at": "...",
               "provider_id": "..." } ],
  "request_id": "..." }
```

```json 400 — all three omitted theme={null}
{ "error": { "message": "Invalid query parameters", "error_code": "request.invalid",
    "details": [ { "field": "appointment_type_id", "message": "Invalid input: expected string, received undefined" },
                 { "field": "from", "message": "Invalid input: expected string, received undefined" },
                 { "field": "to", "message": "Invalid input: expected string, received undefined" } ] },
  "request_id": "..." }
```

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.

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

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

```bash curl theme={null}
curl "https://api-staging.openloophealth.com/v0.1/appointments?patient_id=<patient id>" \
  -H "authorization: Bearer $TOKEN"
```

```json Response theme={null}
{ "items": [ { "id": "<appointment id>", "patient_id": "...", "provider_id": "...",
               "appointment_type_id": "...", "status": "...", "start_at": "...", "end_at": "..." } ],
  "request_id": "..." }
```

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

```bash curl theme={null}
curl -X POST https://api-staging.openloophealth.com/v0.1/reservations \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{ "slot_token": "<from the slot you selected>" }'
```

```json Response theme={null}
{ "data": { "id": "<reservation id>", "expires_at": "..." }, "request_id": "..." }
```

```json 400 — empty body theme={null}
{ "error": { "message": "Invalid request body", "error_code": "request.invalid",
    "details": [ { "field": "slot_token", "message": "Invalid input: expected string, received undefined" } ] },
  "request_id": "..." }
```

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

> [!TIP]
>
> 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
`403`s and what each one means.

> [!TIP]
>
> Locked by check `authorization-403-is-usually-a-wrong-method`.

## What comes back

| Field | Meaning | You key on it for |
| - | - | - |
| `items[].id` (appointment types) | The bookable type for your tenant | `appointment_type_id` on the slots query and the booking |
| `items[].slot_token` (slots) | An opaque handle for one offered time | `POST /v0.1/reservations`, and the booking itself |
| `items[].start_at`, `end_at` (slots) | The offered window | What you show the patient — pass `render_in_timezone` to get it in theirs |
| `items[].status` (appointments) | The appointment's current state | Showing and reconciling a booking |
| `data.id` (reservation) | The hold you created | `DELETE /v0.1/reservations/{id}` to release it |
| `error.details[]` | On a `400`, one entry per rejected field, each naming the `field` | Telling the user which parameter you got wrong |
| `request_id` | Present on every response, success or failure | Support, and any escalation |

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

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

## Related

> [card] [Order status and tracking](https://openloop.mintlify.site/cookbook/order-status-and-tracking.md)
>
> The leg before this one: order status, items and tracking

> [card] [Refills](https://openloop.mintlify.site/cookbook/refills.md)
>
> The next leg: a refill is a questionnaire; the clinician prescribes and you read the new order

> [card] [Retries and idempotency](https://openloop.mintlify.site/cookbook/retries-and-idempotency.md)
>
> When a booking times out: the two appointment writes that require an `Idempotency-Key`


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