# Booking clients

Booking clients are the CRM contacts and companies a booking is made for. The methods in this subsection read the booking clients, replace their whole set, and remove all clients in one call.

Bitrix24 API: `booking.v1.booking.client.list`, `booking.v1.booking.client.set`, `booking.v1.booking.client.unset`
Scope: `booking`

## Operations

- [List booking clients](./clients-list.md) — `GET /v1/bookings/:id/clients`
- [Replace booking clients](./clients-set.md) — `PUT /v1/bookings/:id/clients`
- [Remove booking clients](./clients-delete.md) — `DELETE /v1/bookings/:id/clients`

## Key fields

Fields of a single client. They are returned in every response item of all three methods and passed in the body of the replace request.

| Field | Description |
|------|----------|
| `id` | CRM contact or company ID. Lists: [`GET /v1/contacts`](/docs/entities/contacts/list), [`GET /v1/companies`](/docs/entities/companies/list) |
| `type.module` | Client type module: `crm` |
| `type.code` | Client type code: `CONTACT` — contact, `COMPANY` — company. Dictionary: [`GET /v1/booking-client-types`](/docs/entities/booking-client-types) |

## What to know before you start

1. **The client type comes from the dictionary.** Take the `type.module` and `type.code` pair from [`GET /v1/booking-client-types`](/docs/entities/booking-client-types). A pair that is not in the dictionary is rejected with `400 INVALID_PARAMS` before writing.
2. **Replace, not add.** Replacement writes the set you pass in full: clients missing from the request are removed from the booking. An empty `clients` array removes all of them.
3. **Clients are checked before writing.** A nonexistent contact or company returns `404 ENTITY_NOT_FOUND`, and the booking clients stay unchanged.
4. **A write returns the re-read list.** After writing, replacement and removal read the booking clients again and return them.
5. **A read-only key can read clients.** Replacement and removal with such a key return `403 WRITE_BLOCKED_READONLY_KEY`.
6. **Notifications.** On a resource with notifications enabled, a booking change can send the client an SMS or a messenger message. For test calls, use your own resource with notifications disabled.

## Typical scenario

1. Find a booking: [`GET /v1/bookings`](/docs/entities/bookings/list).
2. Find a contact or company: [`GET /v1/contacts`](/docs/entities/contacts/list), [`GET /v1/companies`](/docs/entities/companies/list).
3. Set the booking clients: [`PUT /v1/bookings/:id/clients`](./clients-set.md).
4. Check the clients: [`GET /v1/bookings/:id/clients`](./clients-list.md).

## Limits

| Limit | Value |
|-------|----------|
| List pagination | None: [`GET /v1/bookings/:id/clients`](./clients-list.md) returns all clients of the booking in one call |
| Request rate | Common API limits — [Limits and optimization](/docs/optimization) |
| Replacement time | Grows with the number of clients: before writing, each contact and company is checked one at a time. Replacing 55 contacts takes about 30 seconds — [Client-side timeout](/docs/optimization#client-side-timeout) |

## See also

- [Bookings](/docs/entities/bookings)
- [Booking client types](/docs/entities/booking-client-types)
- [Wait list clients](/docs/entities/booking-wait-list/clients)
- [Contacts](/docs/entities/contacts)
- [Companies](/docs/entities/companies)