Slot — Booking slot

The atomic building block of FHIR scheduling. A Slot is a time window inside a Schedule with a free / busy status, ready to be consumed by an Appointment.

Purpose of the resource

Slot represents a time interval within a Schedule that may be booked as an Appointment. It's the minimum granularity in the FHIR model: a Slot carries a start–end range, a status, and a reference to the parent Schedule. An Appointment can consume a single Slot (a 15-minute visit) or multiple consecutive Slots (a 90-minute procedure consumes six 15-minute Slots).

Slot mirrors Schedule (its container) and Appointment (the booking that consumes it). The crucial consistency rule: as soon as an Appointment flips to booked, every Slot it references must flip to busy. If the Appointment is cancelled, the Slot(s) revert to free.

Key fields

The R5 StructureDefinition lists eleven top-level elements:

Slot statuses

The status code is mandatory. Official ValueSet SlotStatus, Required binding:

JSON example

A free 15-minute slot in Dr Adam Careful's Schedule on 22 May 2026 at 09:15 Paris time. Category "General Practice", type "Walk-in".

{
  "resourceType": "Slot",
  "id": "example",
  "identifier": [{
    "system": "http://example.org/identifiers/slots",
    "value": "123"
  }],
  "serviceCategory": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/service-category",
      "code": "17",
      "display": "General Practice"
    }]
  }],
  "serviceType": [{
    "concept": {
      "coding": [{
        "system": "http://example.org/service-type",
        "code": "57",
        "display": "Immunization"
      }]
    }
  }],
  "appointmentType": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
      "code": "WALKIN",
      "display": "A previously unscheduled walk-in visit"
    }]
  }],
  "schedule": { "reference": "Schedule/example" },
  "status": "free",
  "start": "2026-05-22T09:15:00+02:00",
  "end": "2026-05-22T09:30:00+02:00",
  "comment": "15-minute slot — first appointment of the morning."
}

Worth pointing out in this example:

• schedule is 1..1 — an orphan Slot doesn't exist: it always belongs to a Schedule.
• The serviceCategory, serviceType, specialty fields duplicate the parent Schedule — their presence here enables fine-grained indexing (e.g. a "General Practice" Schedule with a few "Vaccination"-purpose Slots).
• appointmentType constrains which Appointment type may consume this Slot — useful to reserve a band for new patients.
• status is free: the patient app may propose it.

Searching slots

Typical queries from a booking app:

• GET /Slot?schedule=Schedule/example&status=free&start=ge2026-05-22 — free slots in a given Schedule from a date.
• GET /Slot?schedule.actor=Practitioner/example&status=free — free slots across all Schedules for a practitioner (FHIR chained search).
• GET /Slot?service-type=57&specialty=394814009&status=free — search by service type and specialty, practitioner-agnostic.
• GET /Slot?_count=20&_sort=start&status=free&start=ge2026-05-22&start=lt2026-05-29 — pagination + sort + one-week window.

The Argonaut Scheduling and US Core Scheduling profiles encapsulate those queries in a $find operation exposed on the server root or on Schedule.

Common pitfalls

• Slot without schedule — 1..1 cardinality. Rejected by the validator.
• Slot where end < start — invariant slt-1: end must be later than start. Silent error on some servers.
• Slot and Appointment out of sync — a booked Appointment referencing a free Slot is a business inconsistency. Synchronization is the server's responsibility — typically a database trigger or a FHIR PreCreate hook.
• Slot busy without an Appointment — the inverse: a slot marked busy with no Appointment referencing it. Only legitimate with status=busy-unavailable (break, time off).
• Slot overlaps — FHIR does not forbid two overlapping Slots. Legitimate to model a pairing ("two clinicians on the same hour") but to avoid in a single-practitioner agenda.
• Missing timezone — the FHIR instant type requires an offset. 2026-05-22T09:15:00 is rejected.
• overbooked=true but status=busy — semantic inconsistency. An overbooked Slot should not flip to busy while it still accepts additional bookings.

Related resources

• Schedule — the parent container of the Slot.
• Appointment — the booking that consumes one or more Slots.
• Practitioner, PractitionerRole, Location, Device — actors of the parent Schedule.

See also: the FHIR R5 index.