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": 0,
    "note": "Follow-up consultation"
  }'

Body fields: patientId (required), and optionally appointmentId, locationId, practitionerId, priority, and note.

Response:

{
  "id": "c1a2e3d4-5b6f-7890-abcd-ef1234567890",
  "organizationId": "11112222-3333-4444-5555-666677778888",
  "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "appointmentId": null,
  "locationId": null,
  "practitionerId": null,
  "status": "waiting",
  "priority": 0,
  "queueNumber": 3,
  "checkedInAt": "2024-01-15T09:00:00Z",
  "calledAt": null,
  "startedAt": null,
  "completedAt": null,
  "note": "Follow-up consultation",
  "createdAt": "2024-01-15T09:00:00Z",
  "updatedAt": "2024-01-15T09:00:00Z"
}

Priority

The priority field is an optional integer (defaults to 0). A higher value is called first; within the same priority, first-in first-out applies (by check-in time). The queueNumber is the ticket number assigned automatically per day and location.

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": 5,
    "queueNumber": 1,
    "checkedInAt": "2024-01-15T08:45:00Z",
    "calledAt": null,
    "startedAt": null,
    "completedAt": null,
    "note": null
  },
  {
    "id": "e5f6a7b8-c9d0-1234-ef56-78901234abcd",
    "patientId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "status": "waiting",
    "priority": 0,
    "queueNumber": 2,
    "checkedInAt": "2024-01-15T08:55:00Z",
    "calledAt": null,
    "startedAt": null,
    "completedAt": null,
    "note": null
  }
]

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

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": [...],
  "inProgress": [...],
  "completed": [...]
}

Queue Statistics

Returns today’s stats grouped by status. The response is an array of { status, count, avgWaitMinutes } objects, where avgWaitMinutes is the average minutes waited until being called (may be null):

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

Response:

[
  { "status": "waiting", "count": 4, "avgWaitMinutes": 12.5 },
  { "status": "completed", "count": 35, "avgWaitMinutes": 18.2 },
  { "status": "no-show", "count": 3, "avgWaitMinutes": null }
]

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