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

Node operations

Actions on an existing organizational structure node: fetching child nodes, the total count, moving within the tree, and managing linked communication channels.

Bitrix24 API: humanresources.node.* Scope: humanresources

Child nodes

GET /v1/humanresources/nodes/:id/children

Returns the direct child nodes of the specified organizational structure node — departments and teams one level below in the tree. Nesting deeper than the first level is not expanded.

Parameters

Parameter Type Required Description
id (path) number yes Parent node identifier. List nodes: GET /v1/humanresources/nodes?type=DEPARTMENT

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/humanresources/nodes/17/children" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

const { success, data } = await res.json()
console.log(`Child nodes: ${data.items.length}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes/17/children', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data.items array Array of child nodes
data.items[].id number Node identifier
data.items[].name string Node name
data.items[].type string Node type: DEPARTMENT or TEAM
data.items[].structureId number Identifier of the structure the node belongs to
data.items[].parentId number Parent node identifier — matches :id in the request
data.items[].description string | null Node description. null if no description is set
data.items[].accessCode string Node access code (for example, D185 for a department, SN23 for a team)
data.items[].userCount number Number of employees in the node
data.items[].colorName string | null Node color name. null if no color is set
data.items[].xmlId string | null External node identifier. null if not set
data.items[].createdAt string | null Creation date (ISO 8601). null for nodes created without a timestamp
data.items[].updatedAt string | null Last modification date (ISO 8601). null if there were no changes

Response example

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "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
      }
    ]
  }
}

Error response example

400 — :id is not a positive integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "id must be a positive integer"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS :id is not a positive integer (0, negative, or a non-numeric value)
403 SCOPE_DENIED The key is missing the humanresources scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

The node array is nested under data.items. Unlike the node list, where records sit in a flat data, child nodes are located under data.items.

Only direct descendants are returned. The response contains nodes exactly one level below the parent. To build the full subtree, call the endpoint recursively for each node in data.items that has its own descendants.

See also