Retrieve a waitlist entry
const url = 'https://api.useservice.app/v1/waitlist-entries/example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.useservice.app/v1/waitlist-entries/example \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Waitlist entry public id (wl_…)
Query Parameters
Section titled “Query Parameters”expand=guest inlines the full guest profile and therefore requires the guests:read scope.
Header Parameters
Section titled “Header Parameters”Pin this request to a dated version of the contract, e.g. 2026-09-01. Omit it and the version pinned on the API key applies. A version we do not publish is a 400 bad_request with param: "Service-Version". The version that was applied comes back on the Service-Version response header, always.
Responses
Section titled “Responses”Waitlist entry found
object
The object type: always waitlist_entry.
The entry’s id, wl_…. Opaque and permanent.
Where the entry is in the queue.
active: waiting.offered: a place has been offered to the guest and the offer is still open.suggested: a booking has been proposed to the restaurant’s staff, who decide.promoted: it became a booking — seereservation.cancelled: the guest or the restaurant withdrew it.expired: it ran out of time: the service passed, or the offers ran out.
How the guest joined the queue. Not called source, which means something else on a
reservation and on a guest.
widget: in the restaurant’s booking widget.staff: added by the restaurant’s staff.partner_platform: in the booking widget embedded on a partner’s page.
The service day the guest wants a table on, YYYY-MM-DD in the restaurant’s timezone.
How many guests the entry is for.
The earliest start time the guest will take a table at, HH:MM on service_date in the restaurant’s timezone. With window_end it is the range the matching engine may offer inside — a slot outside it is never offered to this entry. Read it with window_start_day_offset, which says whether the clock time belongs to the service date or to its post-midnight tail.
The latest start time the guest will take, HH:MM on service_date in the restaurant’s timezone, read with window_end_day_offset. Always at or after window_start once both offsets are applied, so a window that runs past midnight — 23:30 to 00:30 — is window_end_day_offset: 1, not a wrapped clock time.
0 = the service date, 1 = its post-midnight tail.
0 = the service date, 1 = its post-midnight tail.
The name of the service the guest joined for, as it was shown to them when they joined — a later rename does not change it. null when that service had no name.
That service’s start, wall-clock HH:MM in the restaurant’s timezone, as it was when the guest joined. null when not recorded.
That service’s end, in the same form. null when not recorded.
The guest’s own request, as they typed it when joining. Guest data: present only when your key carries guests:read; otherwise the field is absent, not null. Every webhook delivery carries it.
The booking this entry became, once it is one a consumer can fetch. Null while an offer is still open — that hold is not a published booking.
A guest profile from the restaurant’s guest book. Guest data: served by GET /v1/guests and ?expand=guest, both of which need the guests:read scope, and carried by every guest.* webhook delivery.
object
The object type: always guest.
The guest’s id, gst_…. Opaque and permanent. When two profiles are merged, the one that disappears keeps resolving to the survivor in ?id= on GET /v1/guests.
First name. A profile has a first name or a last name, possibly both; null when it has only the other.
Last name. null when the profile has only a first name.
Primary e-mail address, trimmed and lower-cased. null when none is known.
Primary phone number: E.164 (+33612345678) when it could be parsed for the restaurant’s country, otherwise as entered with separators removed — so do not assume E.164. null when none is known.
The restaurant’s own notes on the guest profile: free text written by its staff, or carried over from its previous reservation system — the restaurant’s words about the guest, not the guest’s. A booking’s guest_notes are the guest’s own. null when there are none.
Whether the restaurant has flagged this guest as unwelcome. A flag only: it does not by itself refuse a booking.
Why the guest was flagged — required by the restaurant when it sets blacklisted. null when the guest is not flagged.
Dietary preferences the restaurant recorded, as free-form labels. [] when none.
Allergies the restaurant recorded, as free-form labels. [] when none.
Date of birth, YYYY-MM-DD. null when not recorded.
An anniversary date the restaurant recorded, YYYY-MM-DD. null when not recorded.
Whether the restaurant marked the guest as a VIP.
The language the restaurant writes to this guest in, as an ISO 639-1 code. Set to the restaurant’s primary language when the profile is created unless one is given, so null only on a profile that never had one.
How the restaurant first learned of this guest. Not the same vocabulary as a
reservation’s source.
manual: entered by the restaurant’s staff.widget: first seen booking in the restaurant’s booking widget.import: brought over from the restaurant’s previous reservation system.host_assertion: first seen booking through the widget embedded on a partner’s page, with the partner vouching for their identity.api: first seen on a booking created through this API.website_newsletter: first seen signing up to the newsletter on the restaurant’s website.
Whether the guest agreed to receive marketing e-mail from the restaurant.
When marketing_email_consent last became true, ISO 8601 with the restaurant’s UTC offset. null while consent is false.
Whether the guest agreed to receive marketing text messages from the restaurant.
When marketing_sms_consent last became true, ISO 8601 with the restaurant’s UTC offset. null while consent is false.
How many of the guest’s bookings ended with them seated (seated, partially_seated or completed). Recomputed hourly, so it can trail a visit by up to about two hours.
How many of the guest’s bookings ended no_show. Recomputed like visit_count.
How many of the guest’s bookings were cancelled, counting only bookings whose time has passed — a cancelled booking for next month is not counted until then. Recomputed like visit_count.
When the guest’s earliest visit (a booking counted in visit_count) started: ISO 8601 with the restaurant’s UTC offset, on the calendar day it actually started — a seating after midnight carries the next day’s date. null until they have one. Recomputed like visit_count.
When the guest’s latest visit started, in the same format as first_visit_at. null until they have one. Recomputed like visit_count.
When the profile was created: ISO 8601 with the restaurant’s UTC offset.
When the profile last changed, in the same format. The value updated_since compares against.
When the guest joined: ISO 8601 with the restaurant’s UTC offset.
When the entry last changed, in the same format. The value updated_since compares against.
Example
{ "object": "waitlist_entry", "status": "active", "joined_via": "widget", "guest": { "object": "guest", "language": "fr", "source": "manual" }}The Service-Version header names a version we do not publish
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Headers
Section titled “Headers”Unique id for this request. Quote it to support: it is how a specific call is found in our logs. Generated per request, or echoed from the X-Request-Id you sent.
No API key, or not a live one
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Headers
Section titled “Headers”Unique id for this request. Quote it to support: it is how a specific call is found in our logs. Generated per request, or echoed from the X-Request-Id you sent.
API key lacks the reservations:read scope
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}No such waitlist entry
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Too many requests on the read budget
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Headers
Section titled “Headers”Requests permitted in the read burst
Requests remaining in the read burst
Seconds until the read bucket refills
Which budget the numbers describe. read here.
Seconds to wait before retrying
Unique id for this request. Quote it to support: it is how a specific call is found in our logs. Generated per request, or echoed from the X-Request-Id you sent.