Book a slot. Success means NexHealth accepted the booking and queued the EHR insert; check `ehr_writeback`.

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": "[email protected]" },
    "note": "Prefers morning appointments"
  }'

Example success response

{ "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)