---
title: "Find bookable appointment slots"
method: POST
path: "/intent/booking/search"
tags: ["intent"]
---

# Find bookable appointment slots

`POST /intent/booking/search`

## Request

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

Granted location + visit reason + time window -> ranked slots with opaque
slot tokens. Soft failures return `{ ok: false, reason:, message: }` rather than
HTTP errors - `message` is always present and safe to relay to the caller as-is.

### Example request

```
curl -X POST https://nexhealth.info/intent/booking/search \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{
    "location_id": 42,
    "visit_reason": "cleaning",
    "when": { "earliest_date": "2026-08-10", "days": 7, "parts_of_day": ["morning"] },
    "limit": 5
  }'
```

### Example success response

```json
{ "ok": true,
  "slots": [
    { "slot_token": "slt_9f2c1b7e4a5d6c8b9f2c1b7e4a5d6c8b",
      "start_local": "Mon, Aug 10 · 9:00 AM PDT",
      "start_iso": "2026-08-10T09:00:00-07:00",
      "duration_minutes": 30,
      "provider": "Dr. Sarah Johnson",
      "location": { "location_id": 42, "name": "Main St Dental", "address": "1 Main St, Seattle, WA, 98101" } }
  ],
  "summary": { "searched_locations": 1, "with_availability": 1, "window_days": 7 } }
```

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

| `reason` | Meaning | Recommended agent recovery |
|----------|---------|----------------------------|
| `location_required` | No usable `location_id` supplied. | Call `locations/search` first and pass one of its `location_id`s. |
| `appointment_type_unrecognized` | The visit reason matched nothing bookable. | Offer the user the returned `available_types` and re-call with their choice. |
| `appointment_type_ambiguous` | The visit reason plausibly matches more than one type (or one match too uncertain to auto-book). | Offer the returned `matching_types`, confirm one with the user, then re-call with it as `visit_reason`. |
| `no_availability` | No open slots in the window. | If `next_available_date` is present, offer it and re-call with `earliest_date` set to it. |
| `no_availability_in_requested_times` | Slots exist, but none in the requested `parts_of_day`. | Offer the returned `available_parts_of_day` and re-call with one the user accepts. |

## Request body

- PostIntentBookingSearch: Find bookable appointment slots
  - `location_id` integer, required: A location_id returned by locations/search.
  - `visit_reason` string: Free text, e.g. "cleaning" or "checkup".
  - `when` object
    - `earliest_date` string, date: First acceptable date (default today).
    - `days` integer: Window size in days (default 7, max 14).
    - `parts_of_day` string[]: Filter to parts of the day (location-local).
  - `limit` integer: Max slots to return (default 5, max 10).

## Response `200`

Find bookable appointment slots

---

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