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
Parameterlimit Typenumber Default50 DescriptionNumber of records (up to 5000). When limit > 50 the request is automatically assembled from several pages on the server side
Parameteroffset Typenumber Default0 DescriptionNumber of records to skip: offset=7 starts the selection at the 8th department
Parameterselect Typestring Default— DescriptionField selection: ?select=id,name. Only the listed fields are returned
Parameterfilter Typeobject Default— DescriptionOnly 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 -g "https://vibecode.bitrix24.com/v1/departments?filter[parentId]=1" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "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
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

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
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 order or sort parameter was passed — departments cannot be sorted
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 current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

The Bitrix24 account sets the record order. The API cannot sort the selection. To get departments in a specific order, load all records matching the filter and sort them on the client side. With limit up to 5000, the whole list arrives in a single request.

Conditions in the request body. The same filters can be passed in the body of POST /v1/departments/search instead of the query string.

See also