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

List nodes

GET /v1/humanresources/nodes

Returns a list of a Bitrix24 account's org structure nodes of a single type — departments or teams — with pagination.

Parameters

Parameter Type Required Description
Parametertype (query) Typestring Requiredyes DescriptionType of nodes to return: DEPARTMENT or TEAM. If omitted, the request returns 400 MISSING_REQUIRED_PARAMS
Parameterlimit (query) Typenumber Requiredno DescriptionNumber of records per page
Parameteroffset (query) Typenumber Requiredno DescriptionOffset from the start of the result set, for pagination

If more records of the chosen type exist than fit in limit, meta.hasMore is true. To get the next page, repeat the request with an increased offset (offset = offset + limit) until hasMore becomes false. The response carries no total count — this list has no meta.total field, so rely on meta.hasMore.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/humanresources/nodes?type=DEPARTMENT" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/humanresources/nodes?type=DEPARTMENT" \
  -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/humanresources/nodes?type=DEPARTMENT', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Departments on this page: ${data.length}, has more: ${meta.hasMore}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes?type=DEPARTMENT', {
  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 nodes
Fielddata[].id Typenumber DescriptionNode identifier
Fielddata[].name Typestring DescriptionNode name
Fielddata[].type Typestring DescriptionNode type: DEPARTMENT or TEAM
Fielddata[].structureId Typenumber DescriptionIdentifier of the structure the node belongs to
Fielddata[].parentId Typenumber DescriptionParent node identifier. For the root node it equals 0
Fielddata[].description Typestring | null DescriptionNode description. null if no description is set
Fielddata[].accessCode Typestring DescriptionNode access code, for example D185 or SN23. The prefix is not determined by the node type, and the numeric part may differ from id — take the value from the response
Fielddata[].userCount Typenumber DescriptionNumber of employees in the node
Fielddata[].colorName Typestring | null DescriptionNode color name. null if no color is set
Fielddata[].xmlId Typestring | null DescriptionExternal identifier of the node. null if not set
Fielddata[].createdAt Typestring | null DescriptionCreation date (ISO 8601). null for nodes created without a timestamp
Fielddata[].updatedAt Typestring | null DescriptionLast update date (ISO 8601). null if there were no changes
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 17,
      "name": "Head office",
      "type": "DEPARTMENT",
      "structureId": 1,
      "parentId": 0,
      "description": null,
      "accessCode": "D185",
      "userCount": 0,
      "colorName": null,
      "xmlId": null,
      "createdAt": null,
      "updatedAt": null
    },
    {
      "id": 23,
      "name": "Sales department",
      "type": "DEPARTMENT",
      "structureId": 1,
      "parentId": 17,
      "description": "Direct sales",
      "accessCode": "SN23",
      "userCount": 2,
      "colorName": null,
      "xmlId": null,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "meta": {
    "hasMore": false
  }
}

Error response example

400 — required parameter type not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "GET /v1/humanresources/nodes requires query parameters: type. Example: GET /v1/humanresources/nodes?type=..."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_PARAMS DescriptionRequired parameter type not provided
HTTP400 CodeUNSUPPORTED_FILTER DescriptionA filter by a node field other than type was passed — listing is supported only by type
HTTP400 CodeINVALID_SORT_FIELD Descriptionsort or order was passed — nodes are returned in a fixed order; sorting is not supported
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the humanresources scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

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

Known specifics

Listing only by type. The results cannot be narrowed by an arbitrary node field. A request with filter[name] or filter[parentId] returns 400 UNSUPPORTED_FILTER before reaching Bitrix24, and the message names type as the only accepted key. The only way to limit the output is to specify type and page through with limit and offset. To find nodes by a substring of the name, optionally narrowed to a subtree with parentId, use Search nodes.

See also