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. Deeper levels of nesting are not expanded.

The generic filter parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds Warning: 299 - "filter is not supported on this endpoint and was ignored", and records unsupported-filter use in the server log.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionParent 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.items Typearray DescriptionArray of child nodes
Fielddata.items[].id Typenumber DescriptionNode identifier
Fielddata.items[].name Typestring DescriptionNode name
Fielddata.items[].type Typestring DescriptionNode type: DEPARTMENT or TEAM
Fielddata.items[].structureId Typenumber DescriptionIdentifier of the structure the node belongs to
Fielddata.items[].parentId Typenumber DescriptionParent node identifier — matches :id in the request
Fielddata.items[].description Typestring | null DescriptionNode description. null if no description is set
Fielddata.items[].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.items[].userCount Typenumber DescriptionNumber of employees in the node
Fielddata.items[].colorName Typestring | null DescriptionNode color name. null if no color is set
Fielddata.items[].xmlId Typestring | null DescriptionExternal node identifier. null if not set
Fielddata.items[].createdAt Typestring | null DescriptionCreation date (ISO 8601). null for nodes created without a timestamp
Fielddata.items[].updatedAt Typestring | null DescriptionLast modification date (ISO 8601). null if the node has never been modified

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
HTTP200 CodeWarning: 299 DescriptionThe filter is ignored by default; previous data is preserved and the warning is sent in the Warning header.
HTTP400 (strict mode only) CodeUNSUPPORTED_FILTER DescriptionThe server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data.
HTTP400 CodeINVALID_PARAMS Description:id is not a positive integer (0, negative, or a non-numeric value)
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the humanresources scope
HTTP401 CodeTOKEN_MISSING DescriptionThe 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