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
dateFrom string | number yes — Start of the interval. ISO 8601 ("2026-05-01T00:00:00Z") or Unix seconds (1714521600)
dateTo string | number yes — End of the interval. ISO 8601 or Unix seconds
limit number no 50 Number of records (from 1 to 5000)
offset number no 0 Offset

Form 2 — parameters in a nested filter:

Field Type Required Description
filter.within.dateFrom string | number yes Start of the interval
filter.within.dateTo string | number yes End 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
success boolean Always true on success
data array Array of bookings (each record's fields — see Bookings)
meta.total number Always 0 — the total count is not computed. To determine whether there are more records, use meta.hasMore
meta.hasMore boolean true 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": {
          "timestamp": 1723446900,
          "timezone": "UTC"
        },
        "to": {
          "timestamp": 1723447800,
          "timezone": "UTC"
        }
      },
      "description": null,
      "id": 3,
      "name": null,
      "resourceIds": [1, 3]
    },
    {
      "datePeriod": {
        "from": {
          "timestamp": 1741687200,
          "timezone": "UTC"
        },
        "to": {
          "timestamp": 1741690800,
          "timezone": "UTC"
        }
      },
      "description": null,
      "id": 1,
      "name": "Booking",
      "resourceIds": [1]
    },
    {
      "datePeriod": {
        "from": {
          "timestamp": 1752570000,
          "timezone": "UTC"
        },
        "to": {
          "timestamp": 1752571800,
          "timezone": "UTC"
        }
      },
      "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
400 MISSING_REQUIRED_PARAMS dateFrom or dateTo not passed in any of the allowed forms
400 INVALID_DATE The dateFrom or dateTo value is not ISO 8601 or Unix seconds
400 INVALID_PARAMS limit is less than 1 or is not a number
400 UNSUPPORTED_FILTER filter 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
403 SCOPE_DENIED The API key does not have the booking scope
401 MISSING_API_KEY The X-Api-Key header was not passed
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

See also