Waitlist

When a slot is full, join a customer to the waitlist for that venue / resource / date.

Auth: x-api-key. Entries are scoped to your partner: you only ever see, re-activate or cancel entries your own key created.

Waitlist join is naturally idempotent on (venue_id, resource_id, slot_date, customer_phone) within your partner. There is no idempotency_key. Retrying the same join returns your existing entry, resets its status to waiting and refreshes expires_at.

A customer can be waiting through only one channel for a given venue, resource and date. If another channel (another partner, or the venue's own front desk) already has that customer waiting, your join is refused with 409 WAITLIST_ENTRY_CONFLICT, and that channel's entry is neither returned to you nor changed. Once their entry is no longer waiting (promoted, expired or cancelled), you can join the customer yourself.

Join

POST /api/v1/waitlist
Content-Type: application/json
x-api-key: <your-api-key>

{
  "venue_id": "a0000000-0000-4000-8000-000000000001",
  "resource_id": "badminton-court-1",
  "slot_date": "2026-09-20",
  "customer_phone": "9876543210",
  "customer_name": "Aarav Sharma"
}

Optional expires_in_days (default 7). Omit partner_id.

201: { "entry": { … } } — your entry, created or re-activated.

HTTP	error	Meaning
403	VENUE_NOT_AUTHORIZED	This venue is not granted to your key.
409	WAITLIST_ENTRY_CONFLICT	The customer is already waiting for this venue/resource/date through another channel. Nothing was created or changed.

List

GET /api/v1/waitlist?venue_id=<uuid>&resource_id=badminton-court-1&slot_date=2026-09-20
x-api-key: <your-api-key>

venue_id, resource_id, and slot_date are required. Optional status: waiting | promoted | expired | cancelled.

Cancel an entry

DELETE /api/v1/waitlist/{entryId}
x-api-key: <your-api-key>

204. Missing or not yours → 404.