# Human resources

Organizational structure of a Bitrix24 account: departments and teams, their members and employees. The API lets you build and change the department tree, manage node membership, and search employees — without going through the account UI.

**Scope:** `humanresources` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

## Documentation sections

- [Org-structure nodes](/docs/humanresources/nodes) — create, read, update, list, and search departments and teams (5 endpoints).
- [Node operations](/docs/humanresources/node-operations) — child nodes, counter, moving within the tree, communication channels (5 endpoints).
- [Node members](/docs/humanresources/members) — add, remove, move, and fully replace membership with roles (4 endpoints).
- [Employees](/docs/humanresources/employees) — search by name, subordinates, count, membership in several departments (4 endpoints).

## What to know up front

1. **A node is a department or a team.** The type is set by the `type` value: `DEPARTMENT` (department) or `TEAM` (team). The `type` parameter is required when listing ([node list](/docs/humanresources/nodes/list)) and when creating.
2. **Nodes cannot be deleted via the API.** The section has no node-delete endpoint — the tree changes by creating, updating, and moving nodes.
3. **Member roles depend on the node type.** For a department — `MEMBER_HEAD`, `MEMBER_DEPUTY_HEAD`, `MEMBER_EMPLOYEE`. For a team — `MEMBER_TEAM_HEAD`, `MEMBER_TEAM_DEPUTY_HEAD`, `MEMBER_TEAM_EMPLOYEE`. Full list — in the [Node members](/docs/humanresources/members) section.
4. **Membership is returned only when fetching a single node.** The [node list](/docs/humanresources/nodes/list) and [search](/docs/humanresources/nodes/search) return summary fields without members — membership comes in the [node-get](/docs/humanresources/nodes/get) response.
5. **Listing nodes — by type only.** Narrowing the output by an arbitrary node field is not supported. To find nodes by a substring of the name, use [node search](/docs/humanresources/nodes/search) — `type` and `name` are required.
6. **The response shape depends on the endpoint.** Node listing and search return an array in a flat `data` plus `meta` (`total`, `hasMore`). Child nodes and employee search nest the array in `data.items`. Counters and single nodes return an object in `data`. The exact shape — in each endpoint's "Response fields" section.

## Full example

A JavaScript scenario: create a department, nest a sub-department inside it, assign a head, view the tree, and move the sub-department to the top level.

```javascript
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'

async function api(method, path, body = null) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  if (!res.ok) throw new Error(`${method} ${path} → ${res.status}`)
  return res.json()
}

// 1. Create a department at the top level
const { data: parent } = await api('POST', '/humanresources/nodes', {
  type: 'DEPARTMENT',
  name: 'Development department',
  parentId: 1,
})
console.log(`Department created: ${parent.id}`)

// 2. Create a sub-department inside it
const { data: child } = await api('POST', '/humanresources/nodes', {
  type: 'DEPARTMENT',
  name: 'Testing group',
  parentId: parent.id,
})

// 3. Assign the department head
await api('POST', `/humanresources/nodes/${parent.id}/members/add`, {
  userIds: [42],
  role: 'MEMBER_HEAD',
})

// 4. View the department's child nodes
const { data: children } = await api('GET', `/humanresources/nodes/${parent.id}/children`)
console.log(`Child nodes: ${children.items.length}`)

// 5. Move the sub-department to the top level
await api('POST', `/humanresources/nodes/${child.id}/move`, { parentId: 1 })
console.log('Sub-department moved to the top level')
```

## Endpoint reference

All 18 endpoints of the section. Links lead to pages with parameters, examples, and error codes.

**Org-structure nodes:**

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|---------|
| GET | [`/v1/humanresources/nodes`](/docs/humanresources/nodes/list) | humanresources.node.list | List of nodes of the selected type |
| GET | [`/v1/humanresources/nodes/:id`](/docs/humanresources/nodes/get) | humanresources.node.get | Node with its membership |
| POST | [`/v1/humanresources/nodes`](/docs/humanresources/nodes/create) | humanresources.node.add | Create a department or team |
| PATCH | [`/v1/humanresources/nodes/:id`](/docs/humanresources/nodes/update) | humanresources.node.edit | Update a node |
| POST | [`/v1/humanresources/nodes/search`](/docs/humanresources/nodes/search) | humanresources.node.search | Search nodes by name |

**Node operations:**

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|---------|
| GET | [`/v1/humanresources/nodes/:id/children`](/docs/humanresources/node-operations/children) | humanresources.node.children | Child nodes |
| GET | [`/v1/humanresources/nodes/count`](/docs/humanresources/node-operations/count) | humanresources.node.count | Number of nodes by type |
| POST | [`/v1/humanresources/nodes/:id/move`](/docs/humanresources/node-operations/move) | humanresources.node.move | Move a node within the tree |
| GET | [`/v1/humanresources/nodes/:id/communications`](/docs/humanresources/node-operations/communications-get) | humanresources.node.communication.list | Node communication channels |
| PATCH | [`/v1/humanresources/nodes/:id/communications`](/docs/humanresources/node-operations/communications-set) | humanresources.node.communication.edit | Configure communication channels |

**Node members:**

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|---------|
| POST | [`/v1/humanresources/nodes/:id/members/add`](/docs/humanresources/members/add) | humanresources.node.member.add | Add members |
| POST | [`/v1/humanresources/nodes/:id/members/remove`](/docs/humanresources/members/remove) | humanresources.node.member.remove | Remove members |
| POST | [`/v1/humanresources/nodes/:id/members/move`](/docs/humanresources/members/move) | humanresources.node.member.move | Move members |
| POST | [`/v1/humanresources/nodes/:id/members/set`](/docs/humanresources/members/set) | humanresources.node.member.set | Replace membership |

**Employees:**

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|---------|
| POST | [`/v1/humanresources/employees/search`](/docs/humanresources/employees/search) | humanresources.employee.search | Search employees by name |
| GET | [`/v1/humanresources/employees/:id/subordinates`](/docs/humanresources/employees/subordinates) | humanresources.employee.subordinates | Employee subordinates |
| GET | [`/v1/humanresources/employees/count`](/docs/humanresources/employees/count) | humanresources.employee.count | Number of employees |
| POST | [`/v1/humanresources/employees/multidepartment`](/docs/humanresources/employees/multidepartment) | humanresources.employee.multidepartment | Employees in several departments |

## Error codes

### Section errors

| Code | HTTP | Description |
|-----|------|----------|
| `MISSING_REQUIRED_PARAMS` | 400 | The required `type` parameter was not passed when listing nodes |
| `INVALID_PARAMS` | 400 | Invalid `:id` in manual operations (`id must be a positive integer`) or request-body validation failed |
| `ENTITY_NOT_FOUND` | 404 | Node with the given `id` not found |
| `NOT_FOUND` | 404 | Unknown member operation in the path (allowed: `add`, `remove`, `move`, `set`) |
| `BITRIX_ERROR` | 422 | An unsupported filter was passed when listing nodes |

### System errors

| Code | HTTP | Description |
|-----|------|----------|
| `SCOPE_DENIED` | 403 | The key lacks the `humanresources` scope |
| `TOKEN_MISSING` | 401 | The API key has no Bitrix24 tokens configured |
| `BITRIX_ACCESS_DENIED` | 403 | Insufficient permissions on the Bitrix24 portal |
| `BITRIX_UNAVAILABLE` | 502 | The Bitrix24 portal is unavailable |

Full reference of common errors — [Errors](/docs/errors).

## See also

- [Limits and optimization](/docs/optimization)
- [Batch requests](/docs/batch)