Per gli agenti AI: markdown di questa pagina — /docs-content-en/entities/calendar-resources/bookings.md indice della documentazione — /llms.txt

Gli articoli della documentazione sono attualmente disponibili solo in inglese.

Resource bookings

GET /v1/calendar-resources/bookings

Returns the occupied intervals of calendar resources for a period — when each resource is occupied and by which booking.

Parameters

Parameter Type Required Default Description
ParameterresourceIds (query) Typestring RequiredYes Default— DescriptionComma-separated calendar resource IDs: ?resourceIds=57,59. List: GET /v1/calendar-resources
Parameterfrom (query) Typestring RequiredNo Default— DescriptionPeriod start — a date such as 2026-10-01, or an ISO 8601 date with time. Without from and to, the period runs from 30 days before the current date to 90 days after it. If only to is passed, the period has no start limit
Parameterto (query) Typestring RequiredNo Default— DescriptionPeriod end in the same format. If only from is passed, the period has no end limit

The generic filter parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds Warning: 299 - "filter is not supported on this endpoint and was ignored", and records unsupported-filter use in the server log.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/calendar-resources/bookings?resourceIds=59&from=2025-01-21&to=2025-01-22" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/calendar-resources/bookings?resourceIds=59&from=2025-01-21&to=2025-01-22" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({ resourceIds: '59', from: '2025-01-21', to: '2025-01-22' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/calendar-resources/bookings?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
for (const slot of data) console.log(slot.resourceId, slot.from, slot.to)

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({ resourceIds: '59', from: '2025-01-21', to: '2025-01-22' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/calendar-resources/bookings?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

from and to are returned for every interval; the other fields may be absent.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionOccupied resource intervals
Fielddata[].id Typenumber DescriptionID of the calendar event that occupies the resource
Fielddata[].name Typestring DescriptionEvent name
Fielddata[].resourceId Typenumber DescriptionResource ID from resourceIds
Fielddata[].bookingId Typenumber | null DescriptionResource booking ID
Fielddata[].from Typestring DescriptionInterval start: ISO 8601 date and time with an offset. For an all-day interval — a date without time
Fielddata[].to Typestring DescriptionInterval end in the same format. For an all-day interval — the last day, inclusive
Fielddata[].timezoneFrom Typestring DescriptionStart time zone, for example UTC. Not returned for an all-day interval
Fielddata[].timezoneTo Typestring DescriptionEnd time zone. Not returned for an all-day interval
Fielddata[].skipTime Typeboolean Descriptiontrue — an all-day interval
Fielddata[].accessibility Typestring DescriptionAvailability status in the event, for example busy
Fielddata[].importance Typestring DescriptionEvent importance, for example normal
Fielddata[].eventType Typestring DescriptionEvent type. For a resource booking — #resourcebooking#
Fieldmeta.total Typenumber DescriptionNumber of intervals in the response

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "from": "2025-01-21T09:30:00+00:00",
      "to": "2025-01-21T10:30:00+00:00",
      "id": 7667,
      "name": "Booking: client meeting",
      "resourceId": 59,
      "bookingId": 159,
      "accessibility": "busy",
      "importance": "normal",
      "eventType": "#resourcebooking#",
      "timezoneFrom": "UTC",
      "timezoneTo": "UTC",
      "skipTime": false
    },
    {
      "from": "2025-01-21T11:00:00+00:00",
      "to": "2025-01-21T12:00:00+00:00",
      "id": 7707,
      "name": "Booking: product presentation",
      "resourceId": 59,
      "bookingId": 167,
      "accessibility": "busy",
      "importance": "normal",
      "eventType": "#resourcebooking#",
      "timezoneFrom": "UTC",
      "timezoneTo": "UTC",
      "skipTime": false
    }
  ],
  "meta": {
    "total": 2
  }
}

An all-day interval has dates without time and no timezoneFrom or timezoneTo:

JSON 
{
  "from": "2024-04-14",
  "to": "2024-04-16",
  "id": 7389,
  "name": "Booking: lead",
  "resourceId": 59,
  "bookingId": 155,
  "accessibility": "busy",
  "importance": "normal",
  "eventType": "#resourcebooking#",
  "skipTime": true
}

Error response example

400 — resourceIds is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "resourceIds must be a comma-separated list of positive safe integers"
  }
}

Errors

HTTP Code Description
HTTP200 CodeWarning: 299 DescriptionThe filter is ignored by default; previous data is preserved and the warning is sent in the Warning header.
HTTP400 (strict mode only) CodeUNSUPPORTED_FILTER DescriptionThe server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data.
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionresourceIds is missing or contains anything other than comma-separated positive integers
HTTP400 CodeINVALID_PARAMS Descriptionfrom or to is not an ISO 8601 date
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the calendar scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied the key owner access to bookings
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable, returned bookings in an invalid shape, or returned an interval without a date and time zone
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

Full list of common API errors — Errors.

Known specifics

A non-existent resource does not cause an error. An ID that is not in the resource list returns an empty data with 200 — the same as a resource with no bookings. Check IDs against GET /v1/calendar-resources; otherwise a typo in an ID reads as "the resource is free".

All intervals in one response. There is no pagination: the method returns all intervals for the period. To shorten the response, narrow the period with from and to.

See also