# Booking wait list

The wait list is a queue of clients for whom no free time slot was available for a booking. When time frees up, a wait list record becomes a booking, and a booking can be moved back to the list.

Bitrix24 API: `booking.v1.waitList.*`, `booking.v1.booking.createFromWaitList`
Scope: `booking`

## Operations

- [Create an entry](./booking-wait-list/create.md) — `POST /v1/booking-wait-list`
- [List booking wait list records](./booking-wait-list/list.md) — `GET /v1/booking-wait-list`
- [Get an entry](./booking-wait-list/get.md) — `GET /v1/booking-wait-list/:id`
- [Update an entry](./booking-wait-list/update.md) — `PATCH /v1/booking-wait-list/:id`
- [Delete an entry](./booking-wait-list/delete.md) — `DELETE /v1/booking-wait-list/:id`
- [List clients of a wait list record](./booking-wait-list/clients-list.md) — `GET /v1/booking-wait-list/:id/clients`
- [Replace clients of a wait list record](./booking-wait-list/clients-set.md) — `PUT /v1/booking-wait-list/:id/clients`
- [Remove clients from a wait list record](./booking-wait-list/clients-delete.md) — `DELETE /v1/booking-wait-list/:id/clients`
- [Book from the wait list](./booking-wait-list/booking.md) — `POST /v1/booking-wait-list/:id/booking`

## Key fields

| Field | Description |
|------|----------|
| `id` | Wait list record identifier. List: [`GET /v1/booking-wait-list`](./booking-wait-list/list.md). Used in the path of the record methods, its client methods and the method that creates a booking from it |
| `note` | Note on the record: a string or `null`. The only field accepted when creating or updating a record |
| `clients` | Clients of the record — CRM contacts and companies. Read and written by separate methods: [Wait list clients](./booking-wait-list/clients.md) |
| `resourceIds` | Identifiers of the resources that a booking created from the record reserves. List: [`GET /v1/booking-resources`](/docs/entities/booking-resources/list) |
| `datePeriod` | Time of the booking created from the record: `from` and `to`, each with `timestamp` in Unix seconds and `timezone` in IANA format |

A wait list record consists of two fields — `id` and `note`. Record example — [Get an entry](./booking-wait-list/get.md).

## What to know before you start

1. **A record stores only a note.** Create and update accept a single field, `note`. Any other field in the body is rejected with `400 INVALID_PARAMS`. Resources and time are set later, when a booking is created from the record: [Book from the wait list](./booking-wait-list/booking.md).
2. **Clients go through separate requests.** The record and the list do not contain clients. Clients are written by [`PUT /v1/booking-wait-list/:id/clients`](./booking-wait-list/clients-set.md) and read by [`GET /v1/booking-wait-list/:id/clients`](./booking-wait-list/clients-list.md).
3. **An empty string deletes the note.** `note: null` or a body without `note` keeps the existing note. To delete the note, pass `note: ""`.
4. **A booking from a record deletes the record.** [`POST /v1/booking-wait-list/:id/booking`](./booking-wait-list/booking.md) creates a booking with the record's clients and deletes the record from the list. A request rejected with `400` or `422` does not delete the record. The reverse transfer, [`POST /v1/bookings/:id/wait-list`](/docs/entities/bookings/wait-list), deletes the booking and creates a new record in the list with its own `id`.
5. **Client messages follow the resource settings.** Whether a booking created from a record sends a message to the client depends on the `is*NotificationOn` switches of the [booking resource](/docs/entities/booking-resources/get).
6. **A read-only key can read the list.** The list, the record and its clients are available to it. Creating, updating and deleting a record, replacing and removing clients, creating a booking from a record and the reverse transfer are rejected with `403 WRITE_BLOCKED_READONLY_KEY`.

## Typical scenario

1. Put the client in the queue — create a record with a note: [`POST /v1/booking-wait-list`](./booking-wait-list/create.md).
2. Find a contact or company — [`GET /v1/contacts`](/docs/entities/contacts/list), [`GET /v1/companies`](/docs/entities/companies/list) — and set them as the record's clients: [`PUT /v1/booking-wait-list/:id/clients`](./booking-wait-list/clients-set.md).
3. Review the queue: [`GET /v1/booking-wait-list`](./booking-wait-list/list.md).
4. When time frees up, find a resource — [`GET /v1/booking-resources`](/docs/entities/booking-resources/list) — and create a booking from the record: [`POST /v1/booking-wait-list/:id/booking`](./booking-wait-list/booking.md).
5. If the client declines the booking, move it back to the list: [`POST /v1/bookings/:id/wait-list`](/docs/entities/bookings/wait-list). If the record is no longer needed, delete it: [`DELETE /v1/booking-wait-list/:id`](./booking-wait-list/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Records in a list response | up to 5000. If there are more records, the list responds with `502 BITRIX_RESULT_TOO_LARGE` |
| Pagination | none: the list comes back whole; `limit`, `offset` and `order` are rejected with `400 INVALID_PARAMS` |
| Filtering | none: `filter[createdWithin]` is rejected with `422 BITRIX_ERROR`, and other `filter` fields with `400 INVALID_PARAMS` |
| Request rate | general API limits — [Limits and optimization](/docs/optimization) |

## See also

- [Wait list clients](/docs/entities/booking-wait-list/clients)
- [Move a booking to the wait list](/docs/entities/bookings/wait-list)
- [Booking client types](/docs/entities/booking-client-types)
- [Bookings](/docs/entities/bookings)
- [Booking resources](/docs/entities/booking-resources)
- [Errors](/docs/errors)
- [Limits and optimization](/docs/optimization)