لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/humanresources/nodes.md فهرس التوثيق — /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 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 in the output: DEPARTMENT (department) or TEAM (team). Without the parameter, 400 MISSING_REQUIRED_PARAMS is returned
Parameterlimit (query) Typenumber Requiredno DescriptionNumber of records per page
Parameteroffset (query) Typenumber Requiredno DescriptionOffset 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 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(`Found ${meta.total} departments`)

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.total Typenumber (optional) DescriptionTotal number of nodes of the chosen type. Absent when Bitrix24 does not report the count
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": {
    "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
HTTP400 CodeMISSING_REQUIRED_PARAMS DescriptionRequired parameter type not provided
HTTP422 CodeBITRIX_ERROR DescriptionA filter by a node field was passed — listing is supported only by type
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the humanresources scope
HTTP401 CodeTOKEN_MISSING DescriptionThe 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