---
title: "Check a booking"
method: GET
path: "/intent/booking/status"
tags: ["intent"]
---

# Check a booking

`GET /intent/booking/status`

## Request

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

Booking status by booking_ref, as two independent fields. `booking_status`
(formerly `status`) is `confirmed` while the booking stands and `cancelled` if
the appointment was cancelled or removed after booking. `ehr_writeback` is
`pending` until the appointment reaches the practice's EHR, `confirmed` once it
has, `failed` if the sync to the practice's EHR permanently failed (contact
support - this will not resolve on its own), and `unknown` if the appointment
record can no longer be found (stop polling and verify with the practice).
Practices without an EHR integration have nothing to write back to, so their
bookings stay `pending`. `message` restates the combined state in one sentence
that is safe to relay as-is. `start_iso` tracks the live appointment time (a
practice-side reschedule moves it; `start_local` stays as booked).

### Example request

```
curl 'https://nexhealth.info/intent/booking/status?booking_ref=bkg_4d81f30a6c2e49b7a5d81f30a6c2e49b' \
  -H 'Authorization: Bearer <token>'
```

### Example success response

```json
{ "ok": true,
  "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 |
|----------|---------|----------------------------|
| `booking_not_found` | No booking with this reference is visible to your organization. | Verify the `booking_ref` came from your own booking/book response; there is nothing to retry. |

## Query parameters

- `booking_ref` string, required

## Response `200`

Check a booking

---

[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)