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 Req. Description
type (query) string yes Type of nodes in the output: DEPARTMENT (department) or TEAM (team). Without the parameter, 400 MISSING_REQUIRED_PARAMS is returned
limit (query) number no Number of records per page
offset (query) number no Offset from the start of the selection for pagination

If more records match the chosen type than limit, meta.hasMore is true. To get the next page, repeat the request with an increased offset (offset = offset + limit) until hasMore becomes false. meta.total is present only when Bitrix24 reports the total count; when the count is unknown, 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 app

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(`Found ${meta.total} departments`)

JavaScript — OAuth app

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
success boolean Always true on success
data array Array of nodes
data[].id number Node identifier
data[].name string Node name
data[].type string Node type: DEPARTMENT or TEAM
data[].structureId number Identifier of the structure the node belongs to
data[].parentId number Parent node identifier. For the root node it equals 0
data[].description string | null Node description. null if no description is set
data[].accessCode string Node 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
data[].userCount number Number of employees in the node
data[].colorName string | null Node color name. null if no color is set
data[].xmlId string | null External identifier of the node. null if not set
data[].createdAt string | null Creation date (ISO 8601). null for nodes created without a timestamp
data[].updatedAt string | null Last update date (ISO 8601). null if there were no changes
meta.total number (optional) Total number of nodes of the chosen type. Absent when Bitrix24 does not report the count
meta.hasMore boolean Whether 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": {
    "total": 2,
    "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
400 MISSING_REQUIRED_PARAMS Required parameter type not provided
422 BITRIX_ERROR A filter by a node field was passed — listing is supported only by type
403 SCOPE_DENIED The key lacks the humanresources scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

The full list of common API errors — Errors.

Known specifics

Listing only by type. The selection cannot be narrowed by an arbitrary node field. A request with filter[name] or filter[parentId] returns 422 BITRIX_ERROR with a message about an unrecognized filter expression. 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