Patient Queue

The Patient Queue system manages real-time patient flow within a clinical facility. It handles check-in, waiting room management, consultation tracking, and no-show recording.

Check In a Patient

When a patient arrives at the facility, add them to the queue:

curl -X POST https://api.esus.health/queue/check-in \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "priority": "normal",
    "reason": "Follow-up consultation"
  }'

Response:

{
  "id": "c1a2e3d4-5b6f-7890-abcd-ef1234567890",
  "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "waiting",
  "priority": "normal",
  "checkedInAt": "2024-01-15T09:00:00Z",
  "position": 3
}

Priority Levels

Priority	Use Case
`urgent`	Emergency or urgent care
`high`	Priority patient (elderly, pediatric)
`normal`	Standard appointment
`low`	Routine / non-urgent

Get the Waiting List

curl https://api.esus.health/queue/waiting \
  -H "Authorization: Bearer TOKEN"

Response:

[
  {
    "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "patientId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
    "status": "waiting",
    "priority": "urgent",
    "checkedInAt": "2024-01-15T08:45:00Z",
    "waitTimeMinutes": 15
  },
  {
    "id": "e5f6a7b8-c9d0-1234-ef56-78901234abcd",
    "patientId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "status": "waiting",
    "priority": "normal",
    "checkedInAt": "2024-01-15T08:55:00Z",
    "waitTimeMinutes": 5
  }
]

Call the Next Patient

curl -X POST https://api.esus.health/queue/call-next \
  -H "Authorization: Bearer TOKEN"

The system selects the next patient based on priority and check-in time (higher priority patients are called first; within the same priority, first-in first-out applies).

Consultation Lifecycle

Start Consultation

curl -X POST https://api.esus.health/queue/:id/start \
  -H "Authorization: Bearer TOKEN"

Complete Consultation

curl -X POST https://api.esus.health/queue/:id/complete \
  -H "Authorization: Bearer TOKEN"

Mark as No-Show

curl -X POST https://api.esus.health/queue/:id/no-show \
  -H "Authorization: Bearer TOKEN"

Queue Status Values

Status	Meaning
`waiting`	Patient checked in, waiting to be called
`called`	Patient has been called
`in-consultation`	Consultation is in progress
`completed`	Consultation finished
`no-show`	Patient did not respond when called

Full Queue Board

Fetch the complete board with all statuses — useful for a display screen or reception dashboard:

curl https://api.esus.health/queue/board \
  -H "Authorization: Bearer TOKEN"

Response:

{
  "waiting": [...],
  "called": [...],
  "inConsultation": [...],
  "completed": [...],
  "noShow": [...]
}

Queue Statistics

curl https://api.esus.health/queue/stats \
  -H "Authorization: Bearer TOKEN"

Response:

{
  "date": "2024-01-15",
  "totalCheckedIn": 42,
  "completed": 35,
  "noShow": 3,
  "currentlyWaiting": 4,
  "avgWaitTimeMinutes": 18,
  "avgConsultationTimeMinutes": 12
}

Integration with FHIR Appointments

When a patient checks in, you can link the queue entry to a FHIR Appointment resource to maintain a complete clinical record:

# First, update the Appointment status to "arrived"
curl -X PATCH https://api.esus.health/fhir/Appointment/f6a7b8c9-d0e1-2345-f678-9012345bcdef \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{ "status": "arrived" }'

# Then, check the patient into the queue
curl -X POST https://api.esus.health/queue/check-in \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "priority": "normal" }'