QueueBridge API Reference
Build your integration in hours, not weeks.

What is QueueBridge?

QueueBridge is a smart queue-management platform for hospitals, banks, ministries, and service centers. It coordinates four kinds of clients in real time: a kiosk where customers take tickets, an employee portal where staff call and complete tickets, large-screen displays in the waiting area, and an admin dashboard for operators.

This document covers everything an integration partner needs to embed QueueBridge into another product: how to authenticate, the full ticket lifecycle, the 62 REST endpoints exposed across 9 resource groups, and the SignalR real-time channel that broadcasts every state change as it happens.

System surface

Conceptual model

Three nouns drive every workflow. Departments are top-level service categories (e.g. "Cardiology"). Each department has one or more Sub-Departments — the actual service desks (e.g. "Dr. Ali, Room 12"). Customers take Tickets against a sub-department. Each ticket carries a unique displayNumber like A-H-001 (department prefix · sub-department prefix · daily sequence), and moves through a fixed state machine documented in Ticket Lifecycle.

Quick Start

Three calls to verify your integration is wired correctly. Replace localhost:5050 with the production host once provisioned.

Step 1 — Log in

# Returns: { user: { id, username, name, role, ... }, token: "<base64>" }
curl -X POST http://localhost:5050/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

Step 2 — Read kiosk departments

# Public — returns only departments where isActive AND showOnKiosk are true
curl http://localhost:5050/api/departments/kiosk

Step 3 — Subscribe to real-time updates

SignalR cannot be exercised with cURL — it requires the official @microsoft/signalr client. The full reference is at SignalR Hub; the snippet below is the minimum to verify connectivity.

// npm i @microsoft/signalr
import * as signalR from "@microsoft/signalr";

const connection = new signalR.HubConnectionBuilder()
  .withUrl("http://localhost:5050/queueHub")
  .withAutomaticReconnect()
  .build();

connection.on("TicketCreated", (ticket) => {
  console.log("New ticket:", ticket.displayNumber);
});

await connection.start();
await connection.invoke("JoinDisplay");

Authentication

QueueBridge uses a bearer-token scheme. The token is opaque to the client — treat it as a string. Tokens last 24 hours from the moment of issue.

Token format

The server issues a Base64-encoded string of the form userId:role:expiryTicks — partners do not need to decode it. Just store it from the login response and send it back on each request:

Authorization: Bearer eyJ1c2VySWQiOi...<token>

Roles and permissions

QueueBridge has two roles — admin and user — plus six granular permission codes. Admins implicitly hold every permission. The default permission set assigned to new user accounts is transfer.execute + department.lock.

Login — full reference

See Auth & Users below for the endpoint signature. Expired tokens return 401 Unauthorized with the body { "error": "انتهت صلاحية الجلسة" } (English: "Session expired").

Ticket Lifecycle

Every ticket lives in exactly one of seven states. The diagram below is the canonical state machine — every REST endpoint that mutates a ticket is labelled on the transition it triggers.

State reference

Core Workflows

Four end-to-end scenarios that cover ~95% of real integrations. Each diagram shows the wire-level interaction between client, REST API, and SignalR. The cURL playbook below each diagram lets you reproduce the workflow from the command line.

Workflow 1 — Customer takes a ticket

Playbook

# 1. Issue a ticket
curl -X POST http://localhost:5050/api/tickets \
  -H "Content-Type: application/json" \
  -d '{"departmentId":"dept-123","subDepartmentId":"subdept-456"}'

# Response 200:
# { "ticket": { "id":"...", "displayNumber":"A-H-007", "status":0, ... },
#   "companyName":"...", "departmentName":"...", "roomNumber":"12", "waitingBefore":6 }

Workflow 2 — Employee calls the next ticket

Playbook

# 1. Fetch the next waiting ticket(s)
curl "http://localhost:5050/api/tickets/waiting?subDeptId=subdept-456"

# 2. Call a specific ticket
curl -X PUT http://localhost:5050/api/tickets/ticket-789/call \
  -H "Content-Type: application/json" \
  -d '{"userId":"user-1","userName":"Ahmed"}'

# 3. (Optional) Re-announce
curl -X PUT http://localhost:5050/api/tickets/ticket-789/recall \
  -H "Content-Type: application/json" \
  -d '{"userId":"user-1","userName":"Ahmed"}'

# 4. Mark service started when the customer arrives
curl -X PUT http://localhost:5050/api/tickets/ticket-789/start \
  -H "Content-Type: application/json" -d '{}'

Workflow 3 — Transfer to another sub-department

Playbook

curl -X PUT http://localhost:5050/api/tickets/ticket-789/transfer \
  -H "Content-Type: application/json" \
  -d '{
    "newDepartmentId":"dept-999",
    "newSubDepartmentId":"subdept-pharmacy-1",
    "note":"Needs prescription pickup",
    "keepSameNumber": false
  }'

Workflow 4 — Complete and report

Playbook

# 1. Complete with success
curl -X PUT http://localhost:5050/api/tickets/ticket-789/complete \
  -H "Content-Type: application/json" \
  -d '{"isSuccess":true,"note":"Prescribed antibiotics"}'

# 2. Pull today's KPIs
curl http://localhost:5050/api/reports/daily-summary

# 3. Drill down by sub-department
curl "http://localhost:5050/api/reports/subdepartments?fromDate=2026-05-19&toDate=2026-05-19"

Auth & Users

Login, token verification, and user management. 7 endpoints.

curl -X POST http://localhost:5050/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

{
  "user": {
    "id": "a3f1...",
    "username": "admin",
    "name": "System Admin",
    "role": "admin",
    "assignedSubDepartmentIds": [],
    "permissions": []
  },
  "token": "YTNmMTpsYWRtaW46NjM4NDg..."
}

{ "error": "اسم المستخدم أو كلمة المرور غير صحيحة" }

curl http://localhost:5050/api/auth/verify \
  -H "Authorization: Bearer YTNmMTpsYWRtaW46..."

curl http://localhost:5050/api/users

{
  "username": "reception_1",
  "password": "secret",
  "name": "Reception Desk 1",
  "role": "user",
  "roomNumber": "R-12",
  "assignedSubDepartmentIds": ["subdept-456"],
  "permissions": ["transfer.execute", "department.lock"],
  "isActive": true
}

curl -X POST http://localhost:5050/api/users \
  -H "Content-Type: application/json" \
  -d '{"username":"u1","password":"p","name":"User One","role":"user"}'

Tickets

The core resource. 19 endpoints covering issue, query, call, complete, transfer, postpone, reactivate, and reporting.

curl -X POST http://localhost:5050/api/tickets \
  -H "Content-Type: application/json" \
  -d '{"departmentId":"dept-123","subDepartmentId":"subdept-456"}'

{
  "ticket": {
    "id": "7d18...",
    "referenceNumber": "QT-20260519-00000007",
    "displayNumber": "A-H-007",
    "sequenceNumber": 7,
    "status": 0,
    "createdAt": "2026-05-19T10:30:00Z"
    // ... full Ticket model
  },
  "companyName": "Medical Center",
  "slogan": "Your health, our priority",
  "logo": "data:image/png;base64,...",
  "departmentName": "Cardiology",
  "subDepartmentName": "Dr. Ali",
  "roomNumber": "12",
  "waitingBefore": 6
}

{
  "error": "هذا القسم مغلق مؤقتاً",
  "isClosed": true,
  "closedUntil": "2026-05-19T11:15:00Z",
  "remainingMinutes": 12,
  "reason": "Lunch break"
}

curl http://localhost:5050/api/tickets

curl "http://localhost:5050/api/tickets/waiting?subDeptId=subdept-456"

{ "count": 14 }

curl -X PUT http://localhost:5050/api/tickets/<id>/call \
  -H "Content-Type: application/json" \
  -d '{"userId":"user-1","userName":"Ahmed"}'

{
  "newSequenceNumber": 42,
  "userId": "user-1",
  "userName": "Ahmed"
}

{
  "newDepartmentId": "dept-pharmacy",
  "newSubDepartmentId": "subdept-pharmacy-1",
  "note": "Pickup prescription",
  "userId": "user-1",
  "userName": "Ahmed"
}

{
  "completed": { /* old ticket, status=3 */ },
  "created":   { /* new ticket, status=0 */ }
}

Departments

Top-level service categories. 8 endpoints.

curl http://localhost:5050/api/departments

curl -X POST http://localhost:5050/api/departments \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Cardiology","nameEn":"Cardiology","prefix":"A",
    "color":"#2563eb","icon":"❤️",
    "isActive":true,"showOnKiosk":true,"showOnDisplay":true
  }'

{ "message": "Daily sequences reset" }

Sub-Departments

The actual service desks. Includes the temporary closure facility — closed sub-departments reject new ticket issuance with HTTP 423. 9 endpoints.

curl -X POST http://localhost:5050/api/subdepartments \
  -H "Content-Type: application/json" \
  -d '{
    "departmentId":"dept-123",
    "name":"Dr. Ali",
    "prefix":"H",
    "roomNumber":"12",
    "color":"#22c55e","icon":"👨‍⚕️",
    "isActive":true,"showOnKiosk":true,"showOnDisplay":true
  }'

curl -X PUT http://localhost:5050/api/subdepartments/<id>/close \
  -H "Content-Type: application/json" \
  -d '{"minutes":30,"reason":"Lunch","userId":"user-1","userName":"Ahmed"}'

{
  "ids": ["sub-1", "sub-2", "sub-3"],
  "minutes": 60,
  "reason": "Maintenance",
  "userId": "admin",
  "userName": "Admin"
}

Settings

Global queue configuration. 3 endpoints.

{ "logoBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." }

Display Settings

Configure which departments and sub-departments are shown on each physical display screen. Lets you run multiple displays with different filtering. 6 endpoints.

{
  "departments": [ Department, ... ],
  "subDepartments": [ SubDepartment, ... ]
}

{
  "name": "Lobby East TV",
  "departmentIds": ["dept-1", "dept-2"],
  "subDepartmentIds": [],
  "showAllDepartments": false
}

Reports

Aggregated analytics. All date parameters accept ISO 8601 strings (e.g. 2026-05-19). 4 endpoints.

curl "http://localhost:5050/api/reports/tickets?fromDate=2026-05-01&toDate=2026-05-19&status=Completed"

{
  "id": "...",
  "referenceNumber": "QT-20260519-00000007",
  "displayNumber": "A-H-007",
  "departmentName": "Cardiology",
  "subDepartmentName": "Dr. Ali",
  "status": "Completed",
  "statusAr": "مكتمل",
  "createdAt": "2026-05-19T10:30:00Z",
  "calledAt": "2026-05-19T10:42:00Z",
  "startedAt": "2026-05-19T10:43:00Z",
  "completedAt": "2026-05-19T10:51:00Z",
  "waitingTime": "12د 0ث",    // formatted
  "serviceTime": "9د 0ث",
  "assignedUserId": "user-1",
  "assignedUserName": "Ahmed",
  "isSuccess": true,
  "historyCount": 4
}

{
  "subDepartmentId": "...",
  "subDepartmentName": "Dr. Ali",
  "departmentId": "...",
  "roomNumber": "12",
  "totalTickets": 120,
  "waitingTickets": 3,
  "calledTickets": 1,
  "inProgressTickets": 1,
  "completedTickets": 110,
  "transferredTickets": 3,
  "cancelledTickets": 2,
  "successRate": 97.3,
  "avgWaitingTime": 8.4,   // minutes
  "avgServiceTime": 6.7    // minutes
}

{
  "userId": "user-1",
  "userName": "Ahmed",
  "totalHandled": 48,
  "completedCount": 45,
  "inProgressCount": 1,
  "transferredCount": 2,
  "successRate": 95.6,
  "avgServiceTime": 5.2
}

{
  "date": "2026-05-19T00:00:00",
  "totalTickets": 340,
  "waitingTickets": 14,
  "calledTickets": 3,
  "inProgressTickets": 2,
  "completedTickets": 310,
  "transferredTickets": 8,
  "cancelledTickets": 3,
  "successRate": 96.5,
  "avgWaitingTime": 9.2,
  "avgServiceTime": 5.8
}

License

Hardware-bound activation and employee-seat enforcement. 5 endpoints.

{ "hardwareId": "7F-4C-..." }

{ "isValid": true, "message": "License active" }

{ "licenseKey": "XXXX-XXXX-XXXX-XXXX" }

{
  "currentCount": 12,
  "canAddMore": true,
  "remainingSlots": 8,
  "maxEmployees": 20
}

Text-to-Speech

Server-side proxy to Google Translate's TTS. Returns an MP3 stream. 1 endpoint.

curl "http://localhost:5050/api/tts/speak?text=Welcome&lang=en" --output welcome.mp3

SignalR Hub

Real-time updates are delivered over a single SignalR hub. Every state-changing REST call emits one or more events on this hub so subscribed clients update without polling.

Connection

// Reference connection setup with reconnect, error handling, and join
import * as signalR from "@microsoft/signalr";

const conn = new signalR.HubConnectionBuilder()
  .withUrl("http://localhost:5050/queueHub")
  .withAutomaticReconnect([0, 2000, 5000, 10000, 30000])
  .configureLogging(signalR.LogLevel.Information)
  .build();

conn.onreconnecting(err => console.warn("reconnecting", err));
conn.onreconnected(id => console.log("reconnected", id));
conn.onclose(err => console.error("closed", err));

// Subscribe to events BEFORE start()
conn.on("TicketCreated", ticket => {/* ... */});
conn.on("TicketCalled", ({ ticket, roomNumber, audioSpeech }) => {/* ... */});

await conn.start();
await conn.invoke("JoinDisplay");
// or:
await conn.invoke("JoinSubDepartment", "subdept-456");

Client → Server methods

These are invoked from the client via connection.invoke(name, args). They control which broadcast groups the connection belongs to.

Server → Client events

Subscribe with connection.on(name, handler). Every event below is currently broadcast to all connected clients.

Data Models

Schemas for every DTO returned by the API. All fields use camelCase. Nullable fields are marked ?.

Department

SubDepartment

Ticket

TicketHistory

QueueUser

QueueSettings

Single global record. All fields are present on every response.

DisplaySettings

Error Reference

QueueBridge uses standard HTTP status codes. Error bodies follow one of two shapes, depending on the controller:

// Shape 1 — single error message
{ "error": "<message, often in Arabic>" }

// Shape 2 — used by License and a few others
{ "success": false, "message": "<message>" }

The 423 closed-department payload

This response is unique and worth handling specially — it lets the client display a friendly "back in N minutes" message instead of a generic error.

{
  "error":            "هذا القسم مغلق مؤقتاً",   // "This section is temporarily closed"
  "isClosed":         true,
  "closedUntil":      "2026-05-19T11:15:00Z",         // UTC ISO 8601
  "remainingMinutes": 12,
  "reason":           "Lunch break"                  // nullable
}

CORS, Rate Limits, Versioning

CORS

The server enables a permissive CORS policy that accepts any origin, method, and header, and allows credentials — this is required for SignalR over WebSockets to function across origins. Production deployments behind a reverse proxy should narrow the allowed origin list at the proxy layer.

Rate limits

No rate limiting is currently applied at the API layer. The intended deployment topology — a private LAN with a small number of trusted kiosks, portals, and displays — does not benefit from it. Partners exposing the API over public networks should add a rate-limit layer at their gateway.

Versioning

The current API uses unversioned paths (/api/...). Future breaking changes will be introduced under a versioned prefix (/api/v2/...). The v1 surface documented here will remain available for the duration of any partner agreement.

Pagination

List endpoints currently return full collections. For deployments that grow beyond ~10,000 tickets/day, contact us before integrating with bulk endpoints — pagination is on the roadmap.

Appendix

Glossary

Default seed credentials

Storage notes

QueueBridge persists state in JSON files (tickets.json, users.json, departments.json, subdepartments.json, queue_settings.json, display_settings.json) next to the server binary. Backups are as simple as copying that folder. There is no external database to provision.

Contact & support