# Bookings

Bookings reserve Bitrix24 account resources for a given time interval: create, get by ID, list and search by date range, update, and delete. Each booking is tied to one or more resources and stores a period with a start and an end.

Bitrix24 API: `booking.v1.booking.*`
Scope: `booking`

## Operations

- [Create a booking](./bookings/create.md) — `POST /v1/bookings`
- [List bookings](./bookings/list.md) — `GET /v1/bookings`
- [Get a booking](./bookings/get.md) — `GET /v1/bookings/:id`
- [Update a booking](./bookings/update.md) — `PATCH /v1/bookings/:id`
- [Delete a booking](./bookings/delete.md) — `DELETE /v1/bookings/:id`
- [Search bookings](./bookings/search.md) — `POST /v1/bookings/search`
- [Booking fields](./bookings/fields.md) — `GET /v1/bookings/fields`

## Key fields

### Editable fields

Accepted on [create](./bookings/create.md) and [update](./bookings/update.md).

| Field | Type | Description |
|------|-----|---------|
| `resourceIds` | number[] | IDs of the resources the booking reserves. Required on create, the array cannot be empty. The identifiers come from [List booking resources](/docs/entities/booking-resources/list) |
| `datePeriod` | object | Booking period. The declared write shape has nested `from` and `to` with `timestamp` and `timezone`; reads return ISO 8601 strings in `from` and `to`. Required on create. |
| `name` | string | Booking name. Optional — may be `null` |
| `description` | string | Booking description. Optional — may be `null` |

### Read-only

Returned in the response, not accepted on create or update.

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Booking ID |

## What to know before you start

1. **Two fields are required to create a booking:** `resourceIds` (non-empty array) and `datePeriod`. If either one is missing, the response is `422 BITRIX_ERROR` with the list of missing fields. `name` and `description` are optional.
2. **The declared `datePeriod` write example is nested.** Time is given as `{"from": {"timestamp": 1780132384, "timezone": "UTC"}, "to": {"timestamp": 1780135984, "timezone": "UTC"}}`. `timestamp` is Unix seconds, `timezone` is an IANA-format time zone. Reads return ISO 8601 strings in `from` and `to`.
3. **List and search require a date interval.** `GET /v1/bookings` and `POST /v1/bookings/search` take two mandatory parameters, `dateFrom` and `dateTo` (ISO 8601 format or Unix seconds). Without them the response is `400 MISSING_REQUIRED_PARAMS`. Bookings outside the interval are not included in the response.
4. **Field names stay as they are.** Field names in the response match the names in the request (`resourceIds`, `datePeriod`) — there is no additional case conversion.
5. **The field set is fixed.** All available fields are listed in the "Key fields" section above.

## Typical scenario

1. Create a booking for the required period: [`POST /v1/bookings`](./bookings/create.md).
2. Get bookings for an interval: [`GET /v1/bookings?dateFrom=...&dateTo=...`](./bookings/list.md).
3. Change the period or name: [`PATCH /v1/bookings/:id`](./bookings/update.md).
4. Cancel the booking: [`DELETE /v1/bookings/:id`](./bookings/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Required interval for list and search | `dateFrom` + `dateTo` |
| Default page size | 50 (`limit`) |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [API reference](/docs/api-reference)
- [Booking clients](/docs/entities/bookings/clients)
- [Move a booking to the wait list](/docs/entities/bookings/wait-list)
- [Booking wait list](/docs/entities/booking-wait-list)
- [Booking client types](/docs/entities/booking-client-types)
- [Booking resources](/docs/entities/booking-resources)
- [Booking resource types](/docs/entities/booking-resource-types)
- [Resource work hours](/docs/entities/booking-resources/slots)