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

Update node

PATCH /v1/humanresources/nodes/:id

Updates an org structure node of a Bitrix24 account — a department or a team in the org structure tree. The body carries only the fields to change, flat at the JSON root without a fields wrapper.

Parameters

Parameter Type Req. Description
id (path) number yes Node identifier. List: GET /v1/humanresources/nodes

Request fields (body)

Field Type Req. Description
name string no Node name
description string no Node description
colorName string no Node color code, for example blue or AZURE

The update does not accept the parent or the node type — both are set once, at creation. To move a node elsewhere in the tree, use Move node.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/humanresources/nodes/39" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales department",
    "description": "Updated description"
  }'

curl — OAuth app

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/humanresources/nodes/39" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales department",
    "description": "Updated description"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes/39', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Sales department',
    description: 'Updated description',
  }),
})

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

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes/39', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Sales department',
    description: 'Updated description',
  }),
})

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

Response fields

Returns the full record of the node after the update.

Field Type Description
id number Node identifier
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
userCount number Number of employees in the node
colorName string Node color
xmlId string External identifier of the node
createdAt datetime Creation date. Returned as null in the update response
updatedAt datetime Last update date. Returned as null in the update response
members array List of node members

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 39,
    "name": "Sales department",
    "type": "DEPARTMENT",
    "structureId": 1,
    "parentId": 17,
    "description": "Updated description",
    "accessCode": "SN39",
    "userCount": 0,
    "colorName": "blue",
    "xmlId": null,
    "createdAt": null,
    "updatedAt": null,
    "members": []
  }
}

Error response example

404 — node with the given id not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Record with ID = `0` not found"
  }
}

Errors

HTTP Code Description
404 ENTITY_NOT_FOUND No node with the given id exists
400 READONLY_FIELD The body contains parentId, type, or another field that cannot be changed. The field name is given in message
400 INVALID_PARAMS A passed field failed validation
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

Dates in the update response. The createdAt and updatedAt fields come as null in the update response. To get the current dates, request the node via GET /v1/humanresources/nodes/:id.

See also