For AI agents: markdown of this page — /docs-content-en/entities/bookings/search.md documentation index — /llms.txt

Search bookings

POST /v1/bookings/search

Returns bookings for the given date range. The start and end of the interval are required. Suitable when it is more convenient to pass the request parameters in the body rather than in the query string.

Request fields (body)

Accepts two equivalent forms. Use either one.

Form 1 — parameters at the top level:

Field Type Required Default Description
FielddateFrom Typestring | number Requiredyes Default— DescriptionStart of the interval. ISO 8601 ("2026-05-01T00:00:00Z") or Unix seconds (1714521600)
FielddateTo Typestring | number Requiredyes Default— DescriptionEnd of the interval. ISO 8601 or Unix seconds
Fieldlimit Typenumber Requiredno Default50 DescriptionNumber of records (from 1 to 5000)
Fieldoffset Typenumber Requiredno Default0 DescriptionOffset

Form 2 — parameters in a nested filter:

Field Type Required Description
Fieldfilter.within.dateFrom Typestring | number Requiredyes DescriptionStart of the interval
Fieldfilter.within.dateTo Typestring | number Requiredyes DescriptionEnd of the interval

within is the only key the method reads inside filter, and inside it only dateFrom and dateTo. Any other key (filter.status, for example) is refused with 400 UNSUPPORTED_FILTER before Bitrix24 is called, instead of being ignored in silence: such a condition used to be lost on the way and the answer covered the whole interval. Narrow the rest on your side.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bookings/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2024-01-01T00:00:00Z",
    "dateTo": "2026-12-31T23:59:59Z",
    "limit": 10
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bookings/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2024-01-01T00:00:00Z",
    "dateTo": "2026-12-31T23:59:59Z",
    "limit": 10
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bookings/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dateFrom: '2024-01-01T00:00:00Z',
    dateTo: '2026-12-31T23:59:59Z',
    limit: 10,
  }),
})

const { success, data, meta } = await res.json()
console.log(`Received ${data.length} bookings, hasMore: ${meta.hasMore}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bookings/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dateFrom: '2024-01-01T00:00:00Z',
    dateTo: '2026-12-31T23:59:59Z',
    limit: 10,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of bookings (each record's fields — see Bookings)
Fieldmeta.total Typenumber DescriptionAlways 0 — the total count is not computed. To determine whether there are more records, use meta.hasMore
Fieldmeta.hasMore Typeboolean Descriptiontrue if the number of records matching the condition exceeds limit

The meta fields sit next to data, not inside it. Page through the results using meta.hasMore: a data length equal to limit does not rule out the last page.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "datePeriod": {
        "from": "2024-08-12T07:15:00+00:00",
        "to": "2024-08-12T07:30:00+00:00"
      },
      "description": null,
      "id": 3,
      "name": null,
      "resourceIds": [1, 3]
    },
    {
      "datePeriod": {
        "from": "2025-03-11T10:00:00+00:00",
        "to": "2025-03-11T11:00:00+00:00"
      },
      "description": null,
      "id": 1,
      "name": "Booking",
      "resourceIds": [1]
    },
    {
      "datePeriod": {
        "from": "2025-07-15T09:00:00+00:00",
        "to": "2025-07-15T09:30:00+00:00"
      },
      "description": null,
      "id": 5,
      "name": null,
      "resourceIds": [1]
    }
  ],
  "meta": {
    "total": 0,
    "hasMore": true
  }
}

Error response example

400 — required parameters not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "POST /v1/bookings/search requires { dateFrom, dateTo } at the top level OR { filter: { within: { dateFrom, dateTo } } }. Values are ISO 8601 or Unix seconds."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_PARAMS DescriptiondateFrom or dateTo not passed in any of the allowed forms
HTTP400 CodeINVALID_DATE DescriptionThe dateFrom or dateTo value is not ISO 8601 or Unix seconds
HTTP400 CodeINVALID_PARAMS Descriptionlimit is less than 1 or is not a number
HTTP400 CodeUNSUPPORTED_FILTER Descriptionfilter carried a key other than within, or within carried a key other than dateFrom and dateTo, or filter did not arrive as an object. The request is refused before Bitrix24 is called: such a condition used to be lost in silence and the answer covered the whole interval
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the booking scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

See also