Book a ticket (walk-in or appointment)

Books a ticket against a service. The presence of the time field selects the mode:

Walk-in (no time) — the customer joins the live queue immediately and is
assigned the next sequential number. A customer is optional.

Appointment (with time) — reserves a specific slot returned by
GET /services/{id}/slots. A customer is required — provide exactly one of
customerId or customerExternalId.

Prerequisites

serviceId — an active service in your company.

groupOfServiceId — the service group the service belongs to (from the branch tree).

For appointments: a time from the slots endpoint and an existing customer.

Behavioural notes

The response is the fully-resolved ticket (same shape as GET /tickets/{id}),
including live queueSize and waitingTime for waiting tickets.

time must be a UTC ISO-8601 datetime with a trailing Z and must be in the
future.

If a booking-time business rule fails (e.g. the branch/service is closed, slot full),
the API responds 400 with a localized reason in error.

Success message is Appointment booked successfully. for appointments and
Ticket booked successfully. for walk-ins. HTTP status is 201 in both cases.

Not idempotent — see the Idempotency notes in the API overview.

Booking flow

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location '/v1/tickets/book' \ --header 'X-Locale;' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "serviceId": "6fe8fb8b12", "groupOfServiceId": "7c1f9a3b2d" }'

{ "message": "Appointment booked successfully.", "data": { "id": "k7m2p9x4q1", "ticketNumber": "A042", "status": "upcoming", "statusAt": "2026-06-23T11:05:22.000Z", "type": "appointment", "time": "2026-07-01T09:30:00.000Z", "branch": { "id": "802b33af66", "name": "Seef Mall Branch" }, "service": { "id": "802b33af66", "name": "Account Opening" }, "groupOfService": { "id": "7c1f9a3b2d", "name": "Teller Services" }, "customer": { "id": "9f2c8b7a4e1d6c3f0a5b8e2d7c4f1a9b", "name": "Layla Hassan" }, "bookedAt": "2026-06-23T11:05:22.000Z" } }

Book a ticket (walk-in or appointment)

Request

Responses