#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, and search departments and teams (5 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. Full list — in the Node members section.
4. Membership is returned only when fetching a single node. The node list and search return summary fields without members — membership comes in the node-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 — 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.

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:

Node operations:

Node members:

Employees:

#Error codes

#Section errors

#System errors

Full reference of common errors — Errors.

#See also

• Limits and optimization
• Batch requests