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

Org structure nodes

Manage org structure nodes of a Bitrix24 account — departments and teams: create, read, update, list and search. A node describes a unit in the org structure tree.

Bitrix24 API: humanresources.node.* Scope: humanresources

List nodes

GET /v1/humanresources/nodes

Returns a list of 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 fall under the chosen type than limit, meta.hasMore returns true. To get the next page, repeat the request with an increased offset (offset = offset + limit) until hasMore becomes false.

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 for a department, SN23 for a team)
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 Total number of nodes of the chosen type
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 an explanation about an unrecognized filter expression. The only way to limit the output is to specify type and page through with limit and offset. To select by field values with sorting, use search nodes.

See also