Run the waitlist

The waitlist is a granted location’s walk-in queue. It uses the same access as bookings: your app’s location grant, the per-location bookings rollout, and the bookings:* scopes. It is available at Maple-native locations only; a provider-managed location answers 422 capability_unsupported.

Maple sends every guest text. Notifying a party sends Maple’s table-ready SMS and starts the venue’s response window. You never message waitlist guests yourself.

Scope	What it allows
bookings:read	Read the queue, an entry, and wait estimates.
bookings:write	Add a party, and cancel an entry on the guest’s behalf.
bookings:manage	Act as the venue: notify, seat, and remove parties, and open or close the waitlist.

A guest-facing app usually needs bookings:read and bookings:write. A host-stand or POS app also needs bookings:manage.

Set MAPLE_BASE and MAPLE_KEY as in Take bookings.

1. Read the queue

curl "$MAPLE_BASE/locations/$LOCATION_ID/waitlist" \
  -H "Authorization: Bearer $MAPLE_KEY"

The waitlist lists active entries first in line first, and open says whether remote parties may join. Each waitlist_entry carries its position, the quoted_wait it was given, and the guest’s contact details.

To quote a wait before a party joins:

curl --get "$MAPLE_BASE/locations/$LOCATION_ID/waitlist_estimate" \
  -H "Authorization: Bearer $MAPLE_KEY" \
  --data-urlencode 'party_size=2'

A wait is always a band: parties_ahead counts the parties that compete for the same tables, and wait_minutes gives a min–max range. Parties above 50 answer 422 party_size_out_of_bounds.

2. Add a party

Remote parties can only join an open waitlist. A venue opens it with POST /v1/locations/{locationId}/waitlist/open (bookings:manage).

curl -X POST "$MAPLE_BASE/waitlist_entries" \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "location_id": "'"$LOCATION_ID"'",
    "party_size": 2,
    "guest": { "first_name": "Alex", "last_name": "Quinn", "phone": "+12125551234" },
    "idempotency_key": "'"$JOIN_KEY"'"
  }'

• phone is required: it is the only way Maple can tell the guest their table is ready. Maple stores it normalized to E.164 (US numbers may omit +1). A number Maple cannot text, such as one with an extension, answers 400.
• A closed waitlist answers 409 waitlist_closed.
• idempotency_key works like booking writes: retry a lost response with the same key and body to get the same entry back, even if the waitlist has closed since. The key is scoped to your app across all its locations: the same key with a different body, or sent to another location, answers 409 idempotency_key_reused. See Idempotency.

3. Notify and seat

When a table is about to free up, notify the party:

curl -X POST "$MAPLE_BASE/waitlist_entries/$ENTRY_ID/notify" \
  -H "Authorization: Bearer $MAPLE_KEY"

The entry becomes notified. If the guest does not respond within the venue’s response window, it expires as expired_no_response. Notifying an entry that is no longer waiting returns it unchanged. A location where Maple is not texting guests answers 422 guest_messaging_unavailable: guest texts aren’t rolled out there yet, or the venue turned them off. Seat or remove the party instead.

When the party arrives, seat it:

curl -X POST "$MAPLE_BASE/waitlist_entries/$ENTRY_ID/seat" \
  -H "Authorization: Bearer $MAPLE_KEY"

Maple seats the party at the earliest table that fits it right now, the same way the venue’s host stand seats a walk-in. The entry comes back seated with a booking_id. That walk-in booking (channel: walk_in) reads with GET /v1/bookings/{bookingId} and appears in booking lists like any other booking.

• No table free now answers 409 slot_unavailable; notify or wait, then try again.
• An entry that already left the queue answers 409 illegal_transition.

4. Take a party out of line

Call	Scope	Result
POST /v1/waitlist_entries/{entryId}/cancel	bookings:write	The guest left: removed_by_guest.
POST /v1/waitlist_entries/{entryId}/remove	bookings:manage	The venue removed them: removed_by_venue.

Both return the entry. An entry that already left the queue, whether seated, removed, or expired, is returned unchanged.

POST /v1/locations/{locationId}/waitlist/close stops remote parties from joining. Parties already waiting stay in line.

Entry statuses

Status	Meaning
waiting	In line.
notified	Maple texted the guest that their table is ready.
on_my_way	Reserved for a guest replying that they are on the way. Maple does not set it yet; handle it like notified.
seated	Seated; booking_id names the walk-in booking.
removed_by_guest	The guest left the queue.
removed_by_venue	The venue removed the party.
expired_no_response	The guest did not respond after being notified.

position is set while an entry is active (waiting, notified, on_my_way) and null afterwards.

Staying current

Subscribe to the waitlist events (waitlist_entry.created, .notified, .seated, .removed, .expired) to learn about changes the venue or other apps make. Each event embeds the entry’s latest state. To reconcile after a gap, read GET /v1/locations/{locationId}/waitlist; avoid polling it more often than every 15 seconds. Waitlist calls share the bookings budget of 300 requests per minute per app and environment; see Rate limits.