Book an Appointment

Once a slot is available, book with an Appointment. The slot[] and participant[].actor references use the standard FHIR reference shape.

curl -X POST https://api.esus.health/fhir/Appointment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "booked",
    "serviceType": [{
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/service-type",
        "code": "124",
        "display": "General Practice"
      }]
    }],
    "appointmentType": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
        "code": "NORMAL",
        "display": "Normal appointment"
      }]
    },
    "slot": [
      { "reference": "Slot/c1a2e3d4-5b6f-7890-abcd-ef1234567890" }
    ],
    "participant": [
      {
        "actor": {
          "reference": "Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "display": "John Doe"
        },
        "required": "required",
        "status": "accepted"
      },
      {
        "actor": {
          "reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789",
          "display": "Dr. Sarah Johnson"
        },
        "required": "required",
        "status": "accepted"
      }
    ],
    "reasonCode": [{
      "coding": [{
        "system": "http://snomed.info/sct",
        "code": "185349003",
        "display": "Encounter for check up"
      }]
    }],
    "description": "Annual wellness checkup",
    "minutesDuration": 30
  }'

Appointment Status Flow

proposed → pending → booked → arrived/checked-in → fulfilled
                           ↘ cancelled
                           ↘ noshow
                           ↘ waitlist

Register Patient Arrival

Use PATCH to update only the status (PATCH accepts a partial Appointment body — see Getting Started → CRUD):

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": "arrived" }'

Cancel an Appointment

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": "cancelled",
    "cancelationReason": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/appointment-cancellation-reason",
        "code": "PATIENT",
        "display": "Patient cancelled"
      }]
    }
  }'