---
title: "Book a slot"
method: POST
path: "/intent/booking/book"
tags: ["intent"]
---

# Book a slot

`POST /intent/booking/book`

## Request

- Base URL: `https://nexhealth.info`
- URL: `https://nexhealth.info/intent/booking/book`
- Auth: API key in header `Authorization`

Consumes a `slot_token` from booking/search with patient demographics.

A success response means NexHealth accepted the booking and created the
appointment. The insert into the practice's EHR runs asynchronously afterwards,
so two independent fields describe the result: `booking_status` (formerly
`status`) is NexHealth's view (`confirmed`, or `cancelled` if the appointment
was later cancelled or removed), and `ehr_writeback` is the EHR insert
(`pending` here; poll booking/status until it reads `confirmed`, or `failed`
if the insert died and will not resolve on its own). Practices without an EHR
integration have nothing to write back to, so their bookings stay `pending`.
`message` restates the combined state in one sentence and is always safe to
relay to the caller as-is.

Idempotent by contract: retrying with the same `idempotency_key` returns the
original booking with `replay: true` - never a double-booking. Reusing a key
with different request data is refused as `idempotency_conflict`.

### Example request

```
curl -X POST https://nexhealth.info/intent/booking/book \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{
    "slot_token": "slt_9f2c1b7e4a5d6c8b9f2c1b7e4a5d6c8b",
    "idempotency_key": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "patient": { "first_name": "Jane", "last_name": "Doe",
                 "date_of_birth": "1990-01-15",
                 "phone_number": "5551234567", "email": "jane@example.com" },
    "note": "Prefers morning appointments"
  }'
```

### Example success response

```json
{ "ok": true, "replay": false,
  "message": "Booked in NexHealth. The appointment is queued for insertion into the practice's EHR; poll booking/status until ehr_writeback is confirmed.",
  "booking": { "booking_ref": "bkg_4d81f30a6c2e49b7a5d81f30a6c2e49b",
               "booking_status": "confirmed",
               "ehr_writeback": "pending",
               "appointment_id": 918273,
               "start_local": "Mon, Aug 10 · 9:00 AM PDT",
               "start_iso": "2026-08-10T16:00:00Z",
               "duration_minutes": 30,
               "provider": "Dr. Sarah Johnson",
               "location": { "location_id": 42, "name": "Main St Dental", "address": "1 Main St, Seattle, WA, 98101" },
               "patient": { "first_name": "Jane", "last_name": "Doe" } } }
```

### Reason catalog (branch on `reason` when `ok` is false)

| `reason` | Meaning | Recommended agent recovery |
|----------|---------|----------------------------|
| `slot_not_found` | Unknown or foreign slot token. | Re-run booking/search and book a fresh slot. |
| `slot_expired` | The slot token's hold window lapsed. | Re-run booking/search and book a fresh slot. |
| `slot_taken` | Someone else booked this slot first. | Offer the returned `alternatives`, or re-search. |
| `idempotency_conflict` | This `idempotency_key` is recorded against different request data. | Use a new key for a new request. |
| `patient_fields_required` | The practice's EHR needs more patient fields to create a new patient. | Collect the returned `missing_fields` and retry. |
| `new_patient_not_supported` | This practice cannot accept brand-new patients through the API. | Only book patients that already exist at the practice. |

## Request body

- PostIntentBookingBook: Book a slot
  - `slot_token` string, required: A slot_token returned by booking/search.
  - `idempotency_key` string, required: Caller-chosen key making this booking retry-safe; one key per booking attempt.
  - `patient` object, required
    - `first_name` string, required
    - `last_name` string, required
    - `date_of_birth` string, date, required
    - `phone_number` string
    - `email` string
    - `gender` string
  - `note` string: Free-text note attached to the appointment.

## Response `200`

Book a slot

---

[API](https://skmtc.dev/nexhealth/apis/scheduling-intent-beta.md) - [All operations](https://skmtc.dev/nexhealth/apis/scheduling-intent-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/nexhealth/apis/scheduling-intent-beta/revisions/f69a30d3cf2e?raw)