Medplum Scheduling API - Beta Release

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 by Appointment/$find, which handles single-Schedule lookups as a basic case of its ability to query multiple Schedules at once.
• Removed slot-based Appointment/$book: The slot parameter input to $book has been removed. The operation now only accepts an appointment as input, which can act as a container for the potentially many Slot resources involved in a single atomic booking operation.
• HealthcareService as 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 as HealthcareService resources, and a reference to such a healthcare service must be included to search for available appointments in $find.
• Changed availability format: 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!