> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Run the waitlist

> Read the walk-in queue, quote waits, add parties, and notify, seat, or remove them.

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](/developer-api/guides/take-bookings).

## 1. Read the queue

```bash theme={null}
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:

```bash theme={null}
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`).

```bash theme={null}
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](/developer-api/concepts/idempotency).

## 3. Notify and seat

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

```bash theme={null}
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:

```bash theme={null}
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](/developer-api/webhook-events#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](/developer-api/api-reference#rate-limits).