Skip to content
Maple

    Waitlist

    Add a party to the waitlist

    Adds a party to the end of the queue and returns its entry with its position and quoted wait.

    POSThttps://api.maple.inc/v1/waitlist_entriesAPI key

    Adds a party to the end of the queue and returns its entry with its position and quoted wait. A closed waitlist answers 409 waitlist_closed; a phone Maple cannot text, such as one with an extension, answers 400. Requires bookings:write.

    Authorization

    Send your API key as Authorization: Bearer <key>: mpk_test_… against the sandbox (https://api.staging.maple.inc/v1), mpk_live_… against production. See Authentication. The samples read the key from MAPLE_KEY and the base URL from MAPLE_BASE, as set up in the Quickstart.

    Request body

    application/json, required.

    • location_id string required

      A granted location.

    • party_size integer required

      At least 1.

    • guest object required

    • guest.first_name string required

    • guest.last_name string or null

    • guest.phone string required

    • guest.email string or null

    • idempotency_key string required

      Your unique key for this join, scoped to your app across all its locations. Retrying with the same key and the same request returns the same entry; the same key with a different request, including another location, answers 409 idempotency_key_reused. Up to 255 characters.

    Responses

    200 OK

    • object string required

      Always waitlist_entry.

    • id string required

      Opaque, prefixed bkw_….

    • livemode boolean required

    • created number required

    • location_id string required

    • status string required

      One of waiting, notified, on_my_way, seated, removed_by_guest, removed_by_venue, expired_no_response.

    • party_size integer required

    • position integer or null required

      1-based place in the queue while the entry is active; null once it is seated, removed, or expired.

    • quoted_wait object or null required

      The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted.

    • quoted_wait.parties_ahead integer required

    • quoted_wait.wait_minutes object required

    • quoted_wait.wait_minutes.min integer required

    • quoted_wait.wait_minutes.max integer required

    • joined_at string required

      ISO-8601 UTC instant.

    • notified_at string or null required

      ISO-8601 UTC instant the table-ready text was sent.

    • booking_id string or null required

      The walk-in booking created when the party was seated; read it with GET /bookings/{bookingId}.

    • channel string required

      The channel the party joined on, e.g. api_partner, voice_ai, internal.

    • guest object required

    • guest.first_name string or null required

    • guest.last_name string or null required

    • guest.phone string or null required

      E.164, when the guest left one.

    • guest.phone_last_four string or null required

    • guest.email string or null required

    Errors

    • 400 Bad request DeveloperApiBadRequest

    • 401 Unauthorized DeveloperApiUnauthorized

    • 403 Forbidden DeveloperApiForbidden

    • 404 Not found DeveloperApiNotFound

    • 409 Conflict DeveloperApiConflict

    • 422 Unprocessable DeveloperApiUnprocessable

    • 429 Too many requests DeveloperApiRateLimited

    Every error body names the error in _tag, explains it in message, and says where to report it in feedback. See Errors.

    A 429 also sends Retry-After: Seconds to wait before retrying; also returned as retry_after in the body.