Using the waitlist Status

Appointment has a dedicated waitlist status. When a patient requests a time and no slot is available, record an appointment with status: "waitlist" and no slot[] — when a slot opens up, attach the slot and transition the status to booked.

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

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

Convert Waitlist to Booking

When a slot frees up:

curl -X PATCH https://api.esus.health/fhir/Appointment/d4e5f6a7-b8c9-0123-def4-567890abcdef \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "booked",
    "slot": [
      { "reference": "Slot/c1a2e3d4-5b6f-7890-abcd-ef1234567890" }
    ]
  }'

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. Update it to booked (as above) or flip it to pending first if you need explicit patient confirmation.
3. Record the outreach by creating a Communication FHIR resource (see the Appointment Reminders page for the shape).