Hold Appointment

Overview

hold_appointment places a temporary hold on an appointment slot ahead of booking it with schedule_appointment. Support for a genuine hold depends on the configured scheduling backend: some backends can place a real, brief hold; for backends without a native hold/reservation concept, the call is a safe no-op and returns success=false rather than raising an error.

Always call schedule_appointment once the patient has chosen a slot.

Required Parameters

start (string, ISO 8601 datetime with timezone offset) — e.g. '2025-08-06T08:30:00-05:00'. Use start_date + start_time from a slot returned by search_appointments.

minutes_duration (integer) — duration of the appointment in minutes.

visit_type_id (string) — same visit type code used in search_appointments.

provider_id (string) — same provider NPI used in search_appointments.

department_id (string) — same department/facility ID used in search_appointments.

Optional Parameters

person_id (string) — default None. The b.well FHIR Person ID.

debug (boolean) — default false.

Returns

HoldAppointmentResult:

• success (boolean, optional) — whether a hold was placed. false indicates a safe no-op on a backend with no native hold/reservation concept; true indicates a genuine hold was placed. A real hold attempt that fails returns an error instead of success=false.
• Plus shared base fields: error, urls, meta, debug.

Notes

Placing a hold is optional — it is not a required step before schedule_appointment, and success=false does not mean booking will fail.