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

Employees in several departments

POST /v1/humanresources/employees/multidepartment

Returns employees who belong to several departments of the organizational structure at once. Only those with two or more departments are included in the output, and every department is listed for each of them.

Request fields (body)

The request body may be empty or {}. No filter parameters are accepted — the endpoint always returns the full set of employees with multiple departments.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/employees/multidepartment" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/employees/multidepartment" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/employees/multidepartment', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})

const { success, data } = await res.json()
console.log(`Employees in several departments: ${data.total}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/employees/multidepartment', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.employees Typearray DescriptionArray of employees that belong to several departments
Fielddata.employees[].userId Typenumber DescriptionEmployee identifier
Fielddata.employees[].name Typestring DescriptionEmployee name
Fielddata.employees[].workPosition Typestring | null DescriptionEmployee position. null if the position is not set. Empty string if set without a value
Fielddata.employees[].departments Typearray DescriptionDepartments the employee belongs to. Always two or more elements
Fielddata.employees[].departments[].id Typenumber DescriptionDepartment identifier
Fielddata.employees[].departments[].name Typestring DescriptionDepartment name
Fielddata.total Typenumber DescriptionNumber of employees in the output

Response example

JSON 
{
  "success": true,
  "data": {
    "employees": [
      {
        "userId": 1,
        "name": "John Brown",
        "workPosition": "",
        "departments": [
          { "id": 1, "name": "Company" },
          { "id": 9, "name": "Division" },
          { "id": 11, "name": "Work group" },
          { "id": 23, "name": "Sales department" }
        ]
      },
      {
        "userId": 1269,
        "name": "Michael Davis",
        "workPosition": null,
        "departments": [
          { "id": 1, "name": "Company" },
          { "id": 35, "name": "Wholesale sales department" }
        ]
      },
      {
        "userId": 1271,
        "name": "Anna Miller",
        "workPosition": null,
        "departments": [
          { "id": 1, "name": "Company" },
          { "id": 35, "name": "Wholesale sales department" }
        ]
      }
    ],
    "total": 3
  }
}

Error response example

403 — the key lacks the humanresources scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'humanresources' scope"
  }
}

Errors

HTTP Code Description
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

Only employees with two or more departments are included in the output. An employee with a single department is absent from the response. That is why departments of each record contains at least two elements, and the employees array itself is shorter than the total number of employees from the number of employees.

See also