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 — create, read, update, list, search, and count departments and teams (6 endpoints).
• Node operations — child nodes, counter, moving within the tree, communication channels (5 endpoints).
• Node members — add, remove, move, and fully replace membership with roles (4 endpoints).
• 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) 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. See the Node members section for the full list.
4. Membership is returned only when fetching a single node. The node list and search return summary fields without members — membership is returned in the Get node response.
5. Nodes can be listed 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 — 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. See each endpoint's "Response fields" section for the exact shape.

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.

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 19 endpoints of the section. Links lead to pages with parameters, examples, and error codes.

Org-structure nodes:

Node operations:

Node members:

Employees:

Error codes

Section errors

System errors

Full reference of common errors — Errors.

See also

• Limits and optimization
• Batch requests