API documentation

GET /v1/me

Confirms which organisation a key belongs to and what it can do. The quickest way to check a key works.

GET /v1/locations

Your locations, with addresses, coordinates and timezones.

GET /v1/queues

Your queues and how many people are waiting in each. Filter with location_id.

curl "https://queuejoin.com/api/v1/queues?location_id=LOCATION_ID" \
-H "Authorization: Bearer $QJ_KEY"

GET /v1/queue-entries

Visits, newest first. Filter with status (waiting, called, served, no_show, cancelled), location_id or queue_id.

POST /v1/queue-entries

Add somebody to a queue — from your own booking page, your till, or a kiosk. Requires the write scope. They are notified exactly as if they had scanned your QR code.

curl -X POST https://queuejoin.com/api/v1/queue-entries \
-H "Authorization: Bearer $QJ_KEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "Sam Okafor",
  "mobile_number": "+447911123456",
  "location_id": "LOCATION_ID",
  "party_size": 2
}'

name, mobile_number and location_id are required. mobile_number is in international format, or a national number with its two-letter country code in mobile_number_country ("GB"). email, queue_id, service_id, party_size and notes are optional; without a queue we use the location’s default, and an email address is stored on the customer without replacing one already on file with a blank.

Like a member of staff adding a walk-in, the API is not subject to the limits on the public join form — but a blocked number is refused. Returns 201 with the new entry, or:

• 400 invalid_body, missing_field or invalid_field — the body isn’t JSON, a required field is missing, or a number or email address can’t be read.
• 402 plan_limit_reached — the plan’s visit limit is reached.
• 402 location_locked — the location is beyond what the plan covers.
• 403 number_blocked — you, or Queue Join, have blocked the number there.
• 404 not_found — no such location in your organisation.
• 409 no_queue — the location has no active queue.

GET /v1/queue-entries/{id}

A single visit.

PATCH /v1/queue-entries/{id}

Move a visit on: called, served, no_show or cancelled. Requires the write scope. called sends the customer the message that it is their turn, and cancelled and no_show send theirs, so your customer hears about it either way.

curl -X PATCH https://queuejoin.com/api/v1/queue-entries/ENTRY_ID \
-H "Authorization: Bearer $QJ_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "called"}'

Returns 409 already_closed if the visit is already served, cancelled or marked a no-show — closed visits are not reopened through the API. Staff can undo a serve or a call by mistake on the dashboard, which sends queue_entry.unserved or queue_entry.uncalled.

GET /v1/appointments

Bookings, latest start first. Filter with from and to (ISO dates, on the start time), location_id, or status (booked, confirmed, completed, cancelled, no_show).

POST /v1/appointments

Make a booking — from your own website, phone system or till. Requires the write scope. It is checked against exactly the rules a booking made in the dashboard is, and the customer is told about it the same way.

curl -X POST https://queuejoin.com/api/v1/appointments \
-H "Authorization: Bearer $QJ_KEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "Sam Okafor",
  "mobile_number": "+447911123456",
  "location_id": "LOCATION_ID",
  "service_id": "SERVICE_ID",
  "start_at": "2026-08-29T14:00:00Z"
}'

name, location_id and service_id are required, with a start time given one of two ways: start_at, an ISO 8601 instant that includes Z or an offset; or date (YYYY-MM-DD) and time (HH:MM) in the location’s own time zone. The end time comes from the service’s duration. mobile_number (or a national number with mobile_number_country), email and notes are optional — without a mobile number the customer isn’t messaged.

Your booking settings all apply: whether bookings are on, booking hours, the notice and how far ahead people may book, capacity, the limit per customer, the service’s own rules and resources, and “only existing customers”. With booking approval on, a new booking is booked (a request) until it is confirmed; otherwise it starts confirmed. A booking counts towards your plan’s visit allowance, like a waitlist join. Returns 201 with the booking, or:

• 400 invalid_body, missing_field or invalid_field — the body isn’t JSON, a required field is missing, or a time, number or email address can’t be read.
• 402 location_locked — the location is beyond what the plan covers.
• 402 plan_limit_reached — the plan’s visits for this month are used up.
• 403 number_blocked — you, or Queue Join, have blocked the number there.
• 403 existing_customers_only — the location only takes bookings from existing customers, and this isn’t one.
• 404 not_found — no such location or service in your organisation.
• 409 slot_unavailable — the time can’t be booked. The message says why: outside booking hours, too soon or too far ahead, full, or the customer’s limit reached.

GET /v1/appointments/{id}

A single booking.

PATCH /v1/appointments/{id}

Change a booking: move it to another time, or move it on. One change per request. Requires the write scope.

# Move it
curl -X PATCH https://queuejoin.com/api/v1/appointments/APPOINTMENT_ID \
-H "Authorization: Bearer $QJ_KEY" \
-H "Content-Type: application/json" \
-d '{"date": "2026-08-30", "time": "10:30"}'

# Move it on
curl -X PATCH https://queuejoin.com/api/v1/appointments/APPOINTMENT_ID \
-H "Authorization: Bearer $QJ_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "confirmed"}'

To move it, send start_at, or date and time, as when creating one. The new time is checked against the same rules, and the customer is told it has changed.

To move it on, send status:

• confirmed — accept a booking request. Only for a booking that is still booked.
• arrived and served — stamp arrived_at or served_at. The status doesn’t change.
• completed, no_show and cancelled — close the booking.

Each sends the customer the same message the dashboard button does. Returns the booking as it now stands, or 404 not_found, 400 invalid_status, 409 already_closed (it is completed, cancelled or a no-show), 409 already_confirmed, or 409 slot_unavailable.

A booking has id, status, start_at, end_at, location_id, location_name, timezone, service_id, service_name, resource_id, notes, the customer’s customer_id, customer_name, customer_mobile and customer_email, and the created_at, confirmed_at, arrived_at, delayed_at, served_at, completed_at and cancelled_at times (null until they happen).

GET /v1/customers

Your customer directory. Filter with search, or with marketing_consent=true to get only those who have opted in and not since opted out.