Search Scheduling Slots

Overview

search_scheduling_slots retrieves available scheduling slots (FHIR Slot resources), fanning out across every requested provider/department combination and merging the results. Call this tool when a patient wants to find available appointment times. visit_type_id is required; provider_id and department_id are each optional lists of one or more values (NPIs and facility IDs from provider_search, respectively) — every combination is searched concurrently and merged into one list. If not supplied, the date range defaults to tomorrow through two weeks out.

Required Parameters

visit_type_id (list of strings)

• Visit type code(s) to search for. Only the first value is used today.

Optional Parameters

provider_id (list of strings)

• Default: None
• Provider NPI number(s), as returned in provider_search results (e.g. ['1407856023']).
• Currently required in practice, along with department_id.

department_id (list of strings)

• Default: None
• The facility_id(s) from provider_search results (e.g. ['222126']).
• Currently required in practice, along with provider_id.

specialty (list of strings)

• Default: None
• Provider specialty/specialties to filter by. Accepted for interface symmetry but not currently forwarded to the scheduling backend.

person_id (string)

• Default: None
• The b.well FHIR Person ID. Optional for the default patient.

start_date / end_date (string, YYYY-MM-DD)

• Default: tomorrow / two weeks from today.

reason (string)

• Default: None
• Free-text reason for the visit. Accepted for interface symmetry but not currently forwarded to the scheduling backend.

count (integer)

• Default: None
• Maximum number of slots to return, applied to the merged result.

debug (boolean)

• Default: false

Returns

SchedulingSlotsResult:

• fhir_patient_id (string, optional)
• count (integer, optional) — total slots after merging/truncation.
• slots (list) — each with start_date, start_time, end_date (optional), end_time (optional).
• timezone (string, optional)
• last_scanned_date (string, optional)
• Plus shared base fields: result, error, urls, meta, debug.

Notes

• Typical booking flow: get_visit_types → search_scheduling_slots → schedule_appointment. Reuse the same visit_type_id/provider_id/department_id across calls.
• Also used for rescheduling: get_appointments → search_scheduling_slots → reschedule_appointment.
• Each provider/department pair is queried concurrently. If some pairs fail and others succeed, successful slots are still returned with a warning about which pairs failed. If every pair fails, the tool returns an error.