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

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