Scheduling

info

Medplum Scheduling is currently in alpha.

Welcome to the Medplum Scheduling documentation. We currently support a range of scheduling operations that are available via the FHIR API. The following sections walk through the FHIR resources that are used to model scheduling and how the operations interact with them.

We like to separate scheduling into three main steps:

---

Step 1: Defining Availability

The resources used to model availability for a provider, location, or device and the different service-specific scheduling parameters that can be defined.

The simplest version is a single schedule with a single practitioner and a single service type:

• Defining availability at the actor level — When a provider, location, or device is available via Schedule.
• Defining availability at the service level — Default duration, buffers, and alignment per appointment type via ActivityDefinition.

---

Step 2: Matching Availability

Based on the availability defined in the previous step, we can now find available appointment slots. This is done via the $find operation.

Operation	Description	Status
$find	Find available appointment slots	Alpha

---

Step 3: Consuming Availability

Once a desired slot has been found, the appointment booking process can be handled in several steps.

Operation	Description	Status
$book	Book an appointment	Alpha
$hold	Temporarily hold a slot	In Development
$cancel	Cancel an appointment	In Development

---

Key FHIR Resources

Resource	Purpose
Schedule	Represents a provider's, room's, or device's availability. Each Schedule belongs to exactly one actor.
Slot	A specific time block on a Schedule. Only exists in the datastore for booked or blocked time — free slots are computed on demand.
Appointment	A confirmed booking linking one or more Slots to a patient and provider.
ActivityDefinition	Defines default scheduling parameters (duration, buffers, alignment) for a service type, shared across multiple providers.

Medplum Scheduling FHIR Model Design Decisions

Scheduling can be built in FHIR in many different ways. The key design decisions in Meduplum's specific scheduling FHIR model are:

• Recurring availability does not require pre-generated slots: SyntheticSlot resources are computed on-demand by $find as drafted resources that are not persisted in the datastore until an Appointment is booked. This means you don't need to maintain a bulk set of Slot resources across a planning horizon.

note

Available Slots can still be persisted for one time availability.

• One-to-one actor–Schedule relationship: Medplum's scheduling system requires each Schedule to have exactly one actor. While the FHIR spec allows Schedule.actor to hold multiple references, Medplum enforces a single-actor constraint so that availability can be unambiguously resolved per resource. See Defining Availability for the full model.

• Actors must have a timezone: Every actor referenced by a Schedule — whether a Practitioner, PractitionerRole, Location, or Device must have a timezone set via the FHIR timezone extension:

{
  url: 'http://hl7.org/fhir/StructureDefinition/timezone',
  valueCode: 'America/New_York'
}