---
description: "List waiting-list entries, read invitation details, invite or remove entries, and configure phone requirements."
group: "Resources"
order: 22
---

# Waiting lists

Turn waiting-list entries into event-scoped invitations.

## List and filter {#list-and-filter}

`GET /{event_id}/waitinglists/list_data.json` lists one event; `GET /waitinglists/list_data.json` lists accessible events. Responses contain `items`, `total`, `page` and `events`. Each item includes a `Waitinglist` wrapper, requested product title and invitation expiry where present.

Use `q`, company/event UUID filters, `status` (empty, `waiting`, `invited`), `spotlight` (0/1), `sort` (`name`, `email`, `created`, `ticket`), `direction` (asc/desc) and `page`. Page size is 50. Valid excessive pages clamp to the last page; use total to stop paging. Invalid query values are rejected.

## Read an entry {#read-an-entry}

`GET /{event_id}/waitinglists/detail_data/{waitinglist_id}.json` returns `item`, `invitation`, `products` and `event`. Invitation product/quantity are read from the linked promo-code association. An entry without an invitation can return an empty invitation array. Missing or malformed IDs return 404.

## Issue invitations {#issue-invitations}

PUT `/{event_id}/waitinglists/invite.json` with the selected entry IDs, eligible product and invitation limits.

```
{"Waitinglist":{"ids":["66666666-6666-4666-8666-666666666666"],"product_id_invite":"22222222-2222-4222-8222-222222222222","amount":1,"invite_valid_for_hours":48}}
```

Amount must be 1–50. Accepted validity hours are `0, 24, 48, 72, 168, 336, 744, 1488, 8760`; zero means no expiry. All entries and the invited product must belong to the event.

The action creates replacement invitation codes, revokes previous codes and queues email in a transaction. A failed batch rolls back. Read `status.success`: both success and rejection can return HTTP 200. Re-read entry details before retrying an uncertain request; another invitation can replace the prior code and queue another message. Queuing does not prove mail delivery.

## Remove entries {#remove-entries}

PUT `/{event_id}/waitinglists/index.json` with `{"Waitinglist":{"delete":true,"ids":["..."]}}`. Deletion also revokes linked invitation promo codes transactionally. Require `ok:true` and refresh the list.

## Settings and exports {#settings-and-exports}

PUT `/{event_id}/waitinglists/settings.json` with `{"Meta":{"waitinglist_phone_mandatory":1}}` to require a phone number in the visitor waiting-list form. The result uses `status.success`. CSV and Excel downloads are covered in [Exports](/en-us/docs/exports.md).

## Visitor signup {#visitor-signup}

Visitors join through the ticket shop's `/{event_slug}/waitinglist` form. Its `Waitinglist` fields include product ID, firstname, lastname, email and optional title/phone/donation/date data; the event is assigned and checked by the server. This storefront workflow returns an HTML fragment for AJAX, and does not provide a standalone JSON signup result. Use the [embedded shop](/en-us/docs/embed-ticket-shop.md) for visitor registration.