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

Create node

POST /v1/humanresources/nodes

Creates an org structure node of a Bitrix24 account — a department or a team in the org structure tree. The node type is set by the type field; fields are passed flat at the JSON root without a fields wrapper.

Request fields (body)

Field Type Req. Description
type string yes Node type: DEPARTMENT (department) or TEAM (team)
name string yes Node name
parentId number no Parent node identifier in the tree. List: GET /v1/humanresources/nodes
description string no Node description
colorName string no Node color code, for example blue or AZURE
userIds object no Members by role right at creation: { "MEMBER_HEAD": [1], "MEMBER_EMPLOYEE": [2, 3] }. The key is the role, the value is an array of identifiers (not a flat array, unlike adding members)
moveUsersToNode boolean no Move the employees in userIds to the new node, removing them from their previous ones. Defaults to false
createChat boolean no Create a group chat for the node. Defaults to false
bindingChatIds number[] no Identifiers of existing chats to bind to the node
createChannel boolean no Create a channel for the node. Defaults to false
bindingChannelIds number[] no Identifiers of existing channels to bind
createCollab boolean no Create a collab space for the node. Defaults to false
bindingCollabIds number[] no Identifiers of existing collab spaces to bind
id number RO Node identifier, assigned at creation
structureId number RO Identifier of the structure the node belongs to
accessCode string RO Node access code, generated by the system (for example, SN39)
userCount number RO Number of employees in the node
xmlId string RO External identifier of the node
createdAt datetime RO Creation date
updatedAt datetime RO Last update date

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/nodes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPARTMENT",
    "name": "Sales department",
    "parentId": 1,
    "description": "Active sales managers",
    "colorName": "blue"
  }'

curl — OAuth app

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/nodes" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPARTMENT",
    "name": "Sales department",
    "parentId": 1,
    "description": "Active sales managers",
    "colorName": "blue"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'DEPARTMENT',
    name: 'Sales department',
    parentId: 1,
    description: 'Active sales managers',
    colorName: 'blue',
  }),
})

const { success, data } = await res.json()
console.log('Node ID:', data.id)

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'DEPARTMENT',
    name: 'Sales department',
    parentId: 1,
    description: 'Active sales managers',
    colorName: 'blue',
  }),
})

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

Response fields

Returns the full record of the created node.

Field Type Description
id number Identifier of the created node
name string Node name
type string Node type: DEPARTMENT or TEAM
structureId number Identifier of the structure the node belongs to
parentId number Parent node identifier
description string Node description
accessCode string Node access code generated by the system
userCount number Number of employees in the node. For a new node — 0
colorName string Node color
xmlId string External identifier of the node
createdAt datetime Creation date
updatedAt datetime Last update date
members array List of node members. For a new node — an empty array

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 39,
    "name": "Sales department",
    "type": "DEPARTMENT",
    "structureId": 1,
    "parentId": 1,
    "description": "Active sales managers",
    "accessCode": "SN39",
    "userCount": 0,
    "colorName": "blue",
    "xmlId": null,
    "createdAt": "2026-06-03T13:06:45.000Z",
    "updatedAt": "2026-06-03T13:06:45.000Z",
    "members": []
  }
}

Error response example

400 — required field name not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request object validation failed",
    "validation": [
      {
        "field": "MISSING_NAME",
        "message": "Parameter \"name\" is required."
      }
    ]
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS A required field was not provided. In error.validation — the marker MISSING_NAME (name missing) or MISSING_TYPE (type missing)
403 SCOPE_DENIED The key lacks the humanresources scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

The full list of common API errors — Errors.

Known specifics

Initial node setup in a single request. Besides the base fields, at creation you can immediately set the member roster by role (userIds) and communication tools: create a chat, channel or collab space (createChat / createChannel / createCollab) or bind existing ones by identifiers (bindingChatIds / bindingChannelIds / bindingCollabIds). These fields are optional — without them an empty node is created.

See also