NEnexhealth
intent

Find bookable appointment slots

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

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

reasonMeaningRecommended agent recovery
location_requiredNo usable location_id supplied.Call locations/search first and pass one of its location_ids.
appointment_type_unrecognizedThe visit reason matched nothing bookable.Offer the user the returned available_types and re-call with their choice.
appointment_type_ambiguousThe 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_availabilityNo 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_timesSlots exist, but none in the requested parts_of_day.Offer the returned available_parts_of_day and re-call with one the user accepts.
post/intent/booking/search

Request

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

Request body

location_idinteger required

A location_id returned by locations/search.

visit_reasonstring

Free text, e.g. "cleaning" or "checkup".

limitinteger

Max slots to return (default 5, max 10).

Response

Find bookable appointment slots

Changes

No recorded changes to this operation across all 1 revision of this API.