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

Department search

POST /v1/departments/search

Search for departments with filters. Equivalent to GET /v1/departments with filters, but via POST — more convenient for compound queries with several conditions.

Request fields (body)

Parameter Type Default Description
filter object — Exact 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 }
limit number 50 Number of records (up to 5000)
select string[] — Field 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
success boolean Always true on success
data array Array of departments (see Department fields)
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit
meta.durationMs number Request duration in milliseconds

The meta fields sit next to data, not inside it. Pages must be walked by meta.hasMore: a data length equal to limit does not rule out the last page.

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
400 UNSUPPORTED_FILTER An operator or an unsupported field in the filter. Filter by exact equality or $in on id, name, parentId, headId
403 SCOPE_DENIED The API key does not have the department scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The order parameter is not applied; offset is row-exact. The order field in the request body is accepted without error, but the result order does not change — the Bitrix24 department.get method accepts no sort order. The offset field counts records: offset=7 returns the selection starting at the 8th department. The order itself is Bitrix24's, so for stable page-by-page processing request the entire filter selection and sort on the client side.

See also