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 Req. Description
id (path) number yes Employee 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 app

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 app

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
success boolean Always true on success
data.userId number Identifier of the employee whose subordinates were requested
data.departments array Nodes where the employee is assigned as head. Empty if there are no such nodes
data.departments[].nodeId number Node identifier. Fetch the node: GET /v1/humanresources/nodes/:id
data.departments[].name string Node name
data.departments[].role string Employee role in the node in short form: HEAD (head), without the MEMBER_ prefix
data.departments[].subordinatesCount number Number 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
400 INVALID_PARAMS id is not a positive integer (non-numeric, 0, or negative)
403 SCOPE_DENIED The key lacks the humanresources scope
401 TOKEN_MISSING The 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