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

Employee subordinates

GET /v1/humanresources/employees/:id/subordinates

Returns an employee's subordinates grouped by the org-structure nodes where the employee is assigned as head. For each such node, its name and the number of subordinates are returned.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionEmployee identifier (userId). Search: POST /v1/humanresources/employees/search

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/humanresources/employees/1/subordinates" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

const { success, data } = await res.json()
console.log(`Heads ${data.departments.length} nodes`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/employees/1/subordinates', {
  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.userId Typenumber DescriptionIdentifier of the employee whose subordinates were requested
Fielddata.departments Typearray DescriptionNodes where the employee is assigned as head. Empty if there are no such nodes
Fielddata.departments[].nodeId Typenumber DescriptionNode identifier. Fetch the node: GET /v1/humanresources/nodes/:id
Fielddata.departments[].name Typestring DescriptionNode name
Fielddata.departments[].role Typestring DescriptionEmployee role in the node in short form: HEAD (head), without the MEMBER_ prefix
Fielddata.departments[].subordinatesCount Typenumber DescriptionNumber of subordinates in this node

Response example

JSON 
{
  "success": true,
  "data": {
    "userId": 1,
    "departments": [
      {
        "nodeId": 9,
        "name": "Division",
        "role": "HEAD",
        "subordinatesCount": 0
      },
      {
        "nodeId": 23,
        "name": "Sales department",
        "role": "HEAD",
        "subordinatesCount": 1
      }
    ]
  }
}

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
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer (non-numeric, 0, or negative)
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the humanresources scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

The response field name differs from the request parameter. In the request path the employee is set by the :id segment, while in the response the same employee is returned under the data.userId field. Input — id, output — userId.

Only nodes where the employee is the head are included in the output. The data.departments array contains nodes where the employee has the HEAD role. If the employee heads no node, the array comes back empty. A node stays in the output even when subordinatesCount is 0 — that is, the employee is assigned as head but the node has no subordinates yet.

See also