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.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionDepartment ID. List: GET /v1/departments

Request fields (body)

All fields are optional, but the body must contain at least one of them.

Field Type Description
Fieldname Typestring DescriptionDepartment name
FieldparentId Typenumber DescriptionID of the new parent department, used to move the department within the tree. Must reference an existing department. List: GET /v1/departments
FieldheadId Typenumber DescriptionID of the new department head. Source: GET /v1/users
Fieldsort Typenumber DescriptionOrder among departments at the same level

Full field list — Department fields.

headId is not checked for existence. A nonexistent userId in headId is accepted and stored, and the request returns 200. Only parentId is checked: a nonexistent parent returns 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": "West sales department",
    "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": "West sales department",
    "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: 'West sales department',
    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: 'West sales department',
    headId: 101,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe department after the update. Field descriptions — Department fields
Fielddata.id Typenumber DescriptionDepartment ID
Fielddata.name Typestring DescriptionDepartment name
Fielddata.parentId Typenumber DescriptionParent department ID
Fielddata.headId Typenumber DescriptionDepartment head ID. If no head is assigned, the value is 0 or the field is absent
Fielddata.sort Typenumber DescriptionDepartment order among siblings

Response example

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

Error response example

404 — department not found:

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

Errors

HTTP Code Description
HTTP400 CodeEMPTY_UPDATE_BODY DescriptionThe request body is empty — pass at least one field
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a read-only field, such as id
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo department with this id
HTTP422 CodeBITRIX_ERROR DescriptionparentId references a nonexistent department
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the department scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

See also