Account administration
Integrations
Connecting your own systems: an API key so your software can read and write queues and bookings, and webhooks so it hears about changes without asking. This page covers the settings; the API documentation covers the endpoints.
Where to find it
Account settingsIntegrations Business and above
Needs the permission api_keys.create (create api keys) and webhooks.create (create webhooks). Owners and Admins have every permission by default.
API keys
A key authenticates as your whole organisation. Give each system its own rather than sharing one, so you can revoke a single integration without breaking the others.
Scopes
Each key carries scopes:
read— Read queues, bookings, customers and locationswrite— Add people to queues, make bookings, and move visits and bookings on
Give a key read access unless it genuinely needs to change something. A reporting script has no business being able to cancel visits.
A key is shown once and never again
Only a hash is stored, so a lost key cannot be recovered — it has to be revoked and replaced. Treat one like a password: never in browser code, never in a mobile app, never in a public repository. Anybody holding it can read your customer list.
Webhooks
Register an address and we send it a message when something happens — whether it happened through the API or because a member of staff pressed a button. The events available:
appointment.cancelled— A booking was cancelledappointment.created— A booking was madeappointment.updated— A booking was rescheduled, confirmed, arrived, served, completed or marked a no-showqueue_entry.called— A visitor was called forwardqueue_entry.cancelled— A visitor left the queuequeue_entry.created— A visitor joined a queuequeue_entry.no_show— A visitor did not arrivequeue_entry.served— A visitor was servedqueue_entry.uncalled— A visitor called by mistake was sent back to the queuequeue_entry.unserved— A visitor marked served by mistake was reopened
Things to know before you build against them
- Verify the signature. Otherwise anybody who learns your address can tell your system a customer was served.
- Reply quickly. Do the work afterwards; the request times out after ten seconds.
- Expect duplicates. The same event can arrive twice, so handle it by its identifier.
- Failures are retried six times over about ninety minutes, then given up on. Recent attempts are listed on the page.
What people use it for
- Adding somebody to the queue from a till or a kiosk — they get the same messages as if they had scanned your code, though the checks your join page makes are skipped (see below).
- A join form embedded in your own website rather than linking out.
- Pushing visit data into your own reporting.
- Closing a visit automatically when your point-of-sale takes payment.
Visits created through the API count normally
They draw on your plan’s allowances and send the same messages as a visit created any other way. There is no separate quota.
The API skips the public join protection
Your public join page checks every visitor before letting them in: that the number is a real mobile in a country you accept, that one number or one connection isn’t joining over and over, and, when something looks wrong, a security check. A visit added through the API skips all of that, as one a member of staff adds does, because your system is trusted to have checked who it is adding. Numbers you have blocked are still refused.
Protect a join form built on the API yourself
A join form on your own website that calls the API has none of that protection, so anybody can use it to put strangers’ numbers in your queue and have your account text them. Rate-limit it and put a security check on it, or link to your Queue Join join page instead.
Building against it
Endpoints, request and response shapes, error codes and a worked signature check are in the API documentation, which is public — your developer can read it before you give them a key.