Using the waitlist Status

Appointment has a dedicated waitlist status. When a patient requests a time and no slot is available, you can record an appointment with status: "waitlist" and no slot[].

Important limitation. waitlist is a valid status only at creation time (create does not validate transitions). There is NO outgoing transition from waitlist: the server’s state machine only allows proposed → {pending, cancelled}, pending → {booked, cancelled}, booked → {arrived, cancelled, noshow}, and arrived → {fulfilled, cancelled}. A PATCH/PUT that tries to move from waitlist to booked (or any other status) fails with ValidationError (HTTP 400).

In practice this means a waitlist appointment cannot be “converted”: when a slot frees up you must discard the waitlist entry and create a new appointment as pending (or book directly with $book). See “Convert Waitlist to Booking” below.

Create a Waitlist Entry

curl -X POST https://api.esus.health/fhir/Appointment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "waitlist",
    "serviceType": [{
      "coding": [{ "code": "124", "display": "General Practice" }]
    }],
    "participant": [{
      "actor": {
        "reference": "Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "required": "required",
      "status": "needs-action"
    }],
    "reasonCode": [{
      "coding": [{
        "system": "http://snomed.info/sct",
        "code": "185349003",
        "display": "Annual checkup"
      }]
    }],
    "description": "Waitlist — preferred morning appointments",
    "requestedPeriod": [{
      "start": "2026-04-21T08:00:00Z",
      "end": "2026-04-21T12:00:00Z"
    }],
    "priority": 5
  }'

The optional requestedPeriod[] captures the windows that the patient is willing to attend; priority orders the waitlist (pick a convention in your app and document it for operators).

Search the Waitlist

_sort on Appointment only supports date and status; _sort=priority is NOT supported and silently falls back to ordering by start. Sort the waitlist by priority on the client side.

curl "https://api.esus.health/fhir/Appointment?practitioner=a7b1c2d3-e4f5-6789-abcd-ef0123456789&status=waitlist" \
  -H "Authorization: Bearer YOUR_TOKEN"

Convert Waitlist to Booking

Because waitlist has no outgoing transition, you cannot move the appointment to booked with a PATCH. The supported flow when a slot frees up is to discard the waitlist entry and create the booked appointment fresh:

1. Retire the waitlist entry. waitlist → cancelled is not a valid transition either, so mark it discarded on your application side (for example with an entered-in-error in an admin flow, or simply stop surfacing it). Do not try to reuse it as the booked appointment.
2. Book the slot with $book (recommended), which creates the new Appointment as booked and flips the Slot to busy:

curl -X POST https://api.esus.health/fhir/Appointment/\$book \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "slotId": "c1a2e3d4-5b6f-7890-abcd-ef1234567890",
    "participant": [
      { "actor": { "reference": "Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "required": "required", "status": "accepted" }
    ]
  }'

If you need explicit patient confirmation before committing the slot, create the new appointment as pending with a POST /fhir/Appointment, then transition pending → booked on confirmation (remember manual create does not touch the Slot’s status).

Priority Values

The priority field is a positive integer. Pick a convention and document it for your operators.

Notifying Waitlisted Patients

There is no dedicated Notification resource. When a slot opens, the recommended pattern is:

1. Find the top waitlisted appointment for the schedule.
2. Discard that waitlist entry and create the new appointment (with $book, or as pending if you need explicit patient confirmation) as described above — remember waitlist does not transition to booked.
3. Record the outreach by creating a Communication FHIR resource (see the Appointment Reminders page for the shape).