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

Department search

POST /v1/departments/search

Returns departments matching a filter passed in the request body. Accepts the same conditions as GET /v1/departments.

Request fields (body)

Parameter Type Default Description
Parameterfilter Typeobject Default— DescriptionExact equality and $in (IN set) only, on the fields id, name, parentId, headId. Operators (>, >=, <, <=, !, %, $ne, $contains, $nin) and other fields are not supported — you get 400 UNSUPPORTED_FILTER.
Filtering syntax. Example: { "parentId": 1 }
Parameterlimit Typenumber Default50 DescriptionNumber of records (up to 5000)
Parameteroffset Typenumber Default0 DescriptionNumber of records to skip: "offset": 7 starts the selection at the 8th department
Parameterselect Typestring[] Default— DescriptionField selection: ["id", "name"]

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/departments/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "parentId": 1 },
    "limit": 10
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/departments/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "parentId": 1 },
    "limit": 10
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/departments/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { parentId: 1 },
    limit: 10,
  }),
})

const { success, data, meta } = await res.json()
console.log('Found:', meta.total)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/departments/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { parentId: 1 },
    limit: 10,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of departments (see Department fields)
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter. Present in every response
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds

The meta fields sit next to data, not inside it. Page through the results using meta.hasMore: a page whose data length equals limit can still be the last one.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 47,
      "name": "Sales department",
      "sort": 500,
      "parentId": 1,
      "headId": 99
    },
    {
      "id": 107,
      "name": "Development department",
      "sort": 600,
      "parentId": 1,
      "headId": 1
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false,
    "durationMs": 252
  }
}

Error response example

400 — an operator or an unsupported field in the filter:

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "UNSUPPORTED_FILTER: operators are not supported on 'departments' (near 'id'). Its Bitrix24 method (department.get) filters by exact match only — operators are silently ignored by Bitrix24. Use exact match (field: value) or $in (field: {$in: [...]}) on: id, name, parentId, headId."
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNSUPPORTED_FILTER DescriptionAn operator or an unsupported field in the filter. Filter by exact equality or $in on id, name, parentId, headId
HTTP400 CodeINVALID_SORT_FIELD DescriptionThe body contains an order field — sorting departments is not supported
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the department scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

Known specifics

The Bitrix24 account sets the record order. The API cannot sort the selection. For stable page-by-page processing, request the entire filtered result set in one call and sort it on the client side.

See also