# Booking resources

A booking resource is a specialist, room or piece of equipment that clients book online. Each resource belongs to one type, and a booking reserves one or more resources.

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

## Operations

- [Create a booking resource](./booking-resources/create.md) — `POST /v1/booking-resources`
- [List booking resources](./booking-resources/list.md) — `GET /v1/booking-resources`
- [Get a booking resource](./booking-resources/get.md) — `GET /v1/booking-resources/:id`
- [Update a booking resource](./booking-resources/update.md) — `PATCH /v1/booking-resources/:id`
- [Delete a booking resource](./booking-resources/delete.md) — `DELETE /v1/booking-resources/:id`
- [Get resource work hours](./booking-resources/slots-list.md) — `GET /v1/booking-resources/:id/slots`
- [Set resource work hours](./booking-resources/slots-set.md) — `PUT /v1/booking-resources/:id/slots`
- [Remove resource work hours](./booking-resources/slots-delete.md) — `DELETE /v1/booking-resources/:id/slots`

## Key fields

| Field | Description |
|------|----------|
| `id` | Resource identifier. List: [`GET /v1/booking-resources`](./booking-resources/list.md). Pass it in `resourceIds` when [creating a booking](/docs/entities/bookings/create) |
| `name` | Resource name. Required on create |
| `typeId` | Resource type identifier. List: [`GET /v1/booking-resource-types`](/docs/entities/booking-resource-types/list). Without it, the create request is rejected with `422 BITRIX_ERROR` |
| `isMain` | Main-resource flag. The card returns `true` / `false`; the list returns `"Y"` / `"N"` |
| `is*NotificationOn` | Six switches for client messages: booking info, confirmation request, reminder, feedback request, late-arrival message, cancellation message |
| `description` | Resource description. Returned in the card; the list does not return it |

For the full field list, see [Get a booking resource](./booking-resources/get.md).

## What to know before you start

1. **Client messages are on by default.** A resource created without the `is*NotificationOn` switches gets all six set to `true`. To stop the resource from sending messages to clients, pass all six set to `false` on create.
2. **The request body is flat.** Fields go at the root of the JSON, without a `fields` wrapper. The switches accept `true` / `false` or the strings `"Y"` / `"N"`; the card in the response always returns `true` or `false`.
3. **A resource with work hours cannot be edited.** Editing a resource erases its work hours, so when work hours are set, [`PATCH /v1/booking-resources/:id`](./booking-resources/update.md) responds with `422 BOOKING_RESOURCE_SCHEDULE_CONFLICT` and does not change the resource. The order is: remove the work hours, change the resource, then set the work hours again. For details, see [Resource work hours](./booking-resources/slots.md).
4. **A resource with future bookings cannot be deleted.** While the resource has a booking in the future, [`DELETE /v1/booking-resources/:id`](./booking-resources/delete.md) responds with `422 BITRIX_ERROR`. Delete such bookings first with [`DELETE /v1/bookings/:id`](/docs/entities/bookings/delete).
5. **A read-only key can only read resources.** The list, the card and the work hours are available to it, while create, update, delete and writing work hours respond with `403 WRITE_BLOCKED_READONLY_KEY`.

## Typical scenario

1. Find a suitable resource type: [`GET /v1/booking-resource-types`](/docs/entities/booking-resource-types/list). If none fits, create one: [`POST /v1/booking-resource-types`](/docs/entities/booking-resource-types/create).
2. Create a resource of this type: [`POST /v1/booking-resources`](./booking-resources/create.md).
3. Set the resource's work hours: [`PUT /v1/booking-resources/:id/slots`](./booking-resources/slots-set.md).
4. Before creating a booking for a client, find the resource: [`GET /v1/booking-resources`](./booking-resources/list.md) with the `typeId` or `searchQuery` filter.
5. Create a booking for the client, passing the resource `id` in `resourceIds`: [`POST /v1/bookings`](/docs/entities/bookings/create).

## Limits

| Limit | Value |
|-------|----------|
| Resources in a list response | up to 500. If the Bitrix24 account has more, the list responds with `502 BITRIX_RESULT_TOO_LARGE` — narrow the lookup with `typeId` or `searchQuery` |
| Pagination | none: the list comes back whole. `limit` and `offset` are rejected with `400 INVALID_PARAMS` |
| Request rate | list — up to 20 requests per minute per Bitrix24 account, the other resource and work-hours methods — up to 60 each. All API keys of the Bitrix24 account share one limit. The current limit is returned in the `x-ratelimit-limit` header |
| General API limit | see [Limits and optimization](/docs/optimization) |

## See also

- [Resource work hours](/docs/entities/booking-resources/slots)
- [Booking resource types](/docs/entities/booking-resource-types)
- [Bookings](/docs/entities/bookings)
- [Errors](/docs/errors)
- [Limits and optimization](/docs/optimization)