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

Department list

GET /v1/departments

Returns the list of departments in your Bitrix24 account with support for filtering and field selection.

Parameters

Parameter Type Default Description
limit number 50 Number of records (up to 5000). When limit > 50 the request is automatically assembled from several pages on the server side
select string — Field selection: ?select=id,name. Only the listed fields are returned
filter object — Only exact equality and $in (IN-set) on the fields id, name, parentId, headId. Operators (>, >=, <, <=, !, %, $ne, $contains, $nin) and other fields are not supported — a 400 UNSUPPORTED_FILTER is returned.
Filtering syntax. Example: ?filter[parentId]=1

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/departments?filter[parentId]=1" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/departments?filter[parentId]=1" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/departments?filter[parentId]=1', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} departments`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/departments?filter[parentId]=1', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

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
  }
}

Error response example

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

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "UNSUPPORTED_FILTER: 'sort' is not filterable on 'departments'. Its Bitrix24 method (department.get) filters by exact match only. Filterable: 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

The full list of common API errors — Errors.

Known specifics

Sorting is not supported; offset is row-exact. The order / sort parameter is rejected with 400 INVALID_SORT_FIELD — the Bitrix24 department.get method accepts no sort order; sort on the client side instead. The offset parameter counts records: offset=7 starts at the 8th department. Bitrix24 returns results in pages of 50, so Vibe fetches the page covering the requested position and trims the head. When limit > 50 Vibe assembles the needed pages itself (see the limit parameter above), so the entire department list loads in a single request without manual pagination.

When to use search instead of list: for compound conditions across several fields, POST /v1/departments/search is more convenient — the parameters are passed in the request body.

See also