Medplum Scheduling API - Beta Release | Medplum
After several months of preview as an Alpha product, we are pleased to announce that Medplum's Scheduling API has graduated to Beta.
Medplum's Scheduling API provides an interface for applications to atomically interact with Schedule, Slot, and Appointment resources to safely create and manage bookings without creating scheduling conflicts. Developing a feature like this required the ability to iterate as we learned, and our Alpha period provided exactly that.
What changed during Alpha
We made some breaking changes over the course of the Alpha period to simplify the API surface and support multi-resource scheduling:
- Removed
Schedule/:id/$find: This route has been replaced byAppointment/$find, which handles single-Schedule lookups as a basic case of its ability to query multiple Schedules at once. - Removed slot-based
Appointment/$book: Theslotparameter input to$bookhas been removed. The operation now only accepts anappointmentas input, which can act as a container for the potentially many Slot resources involved in a single atomic booking operation. HealthcareServiceas required service type: Our original specification considered using ActivityDefinition resources as an optional place to store shared service type definitions. After considering the impact it would have when booking appointments with several participants, we decided to require that service types be explicitly defined asHealthcareServiceresources, and a reference to such a healthcare service must be included to search for available appointments in$find.- Changed
availabilityformat: We've chosen a storage format for customizing availability that mirrors the FHIR R5 Availability type. This will let us migrate these definitions easily when Medplum Server adds support for later FHIR releases.
The Beta API surface
The Beta API consists of five operations:
| Operation | Description |
|---|---|
Appointment/$find |
Find available slots across one or more Schedules |
Appointment/$book |
Book an appointment in one step |
Appointment/$hold |
Temporarily hold a slot |
Appointment/$confirm |
Confirm a held appointment |
Appointment/$cancel |
Cancel an appointment |
What Beta means
The core API contract is now stable. Breaking changes are still possible during Beta, but we will note them in release notes and provide a migration path where practical. The API is appropriate for production use in non-critical workflows. See our Alpha & Beta policy for the full details.
Get started
Check out the Scheduling documentation for a full reference, including how to define availability, find open slots, and book appointments.
Thank you to all our partners who experimented with the API during the Alpha period and provided such valuable feedback!