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

Update a department

PATCH /v1/departments/:id

Updates the fields of an existing department. Pass only the fields being changed.

Request fields (body)

Parameter Type Description
name string Department name
parentId number ID of the new parent department — to move the department in the tree. Must reference an existing department. List: GET /v1/departments
headId number New head. Source: GET /v1/users
sort number Order among departments at the same level

Full field list — Department fields.

headId is not checked for existence. Bitrix24 does not validate the user in headId: a nonexistent userId is accepted and stored (a dangling reference), and the request returns 200. Only parentId is validated (a nonexistent parent → 422 BITRIX_ERROR). Confirm the user exists via GET /v1/users before assigning.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/departments/47" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales department West",
    "headId": 101
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/departments/47" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales department West",
    "headId": 101
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/departments/47', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Sales department West',
    headId: 101,
  }),
})

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

JavaScript — OAuth application

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

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

Response fields

Field Type Description
data object The updated department object with all fields — see Fields

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 47,
    "name": "Sales department West",
    "sort": 500,
    "parentId": 1,
    "headId": 101
  }
}

Error response example

404 — department not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "department 9999 not found"
  }
}

Errors

HTTP Code Description
404 ENTITY_NOT_FOUND Department not found
422 BITRIX_ERROR parentId references a nonexistent department. headId is NOT validated (a nonexistent user is accepted)
403 SCOPE_DENIED The API key does not have the department scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

See also