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

Departments

Manage your Bitrix24 account's organizational structure: create, fetch, update, delete, and filter departments. Departments form a tree — every department except the root references its parent via parentId, and employees are assigned to departments through the employee directory.

Bitrix24 API: department.* Scope: department

Create a department

POST /v1/departments

Creates a new department in the Bitrix24 account's organizational structure tree.

Request fields (body)

Parameter Type Required Description
name string yes Department name
parentId number yes Parent department ID. Parent list: GET /v1/departments. For a top-level department use parentId: 1
headId number Department head ID. Source: GET /v1/users
sort number Department order among siblings (a smaller value places it higher in the list). Defaults to 500

You cannot create a second top-level department (without parentId or with parentId: 0) — a Bitrix24 account supports only one root department.

headId is not checked for existence. Bitrix24 does not validate the user in headId: a nonexistent userId is accepted and stored as the department head (a dangling reference), and the request returns 201. 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 POST "https://vibecode.bitrix24.com/v1/departments" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales department",
    "parentId": 1,
    "headId": 99,
    "sort": 500
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/departments" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales department",
    "parentId": 1,
    "headId": 99,
    "sort": 500
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/departments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Sales department',
    parentId: 1,
    headId: 99,
    sort: 500,
  }),
})

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

JavaScript — OAuth application

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

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

Response fields

Field Type Description
id number ID of the created department
name string Name
parentId number Parent department ID
headId number Head ID (if provided on creation)
sort number Sort order

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 189,
    "name": "Sales department",
    "sort": 500,
    "parentId": 1,
    "headId": 99
  }
}

Error response example

422 — required field name not provided (with a valid parentId):

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Section name is not entered."
  }
}

Validation order: parentId is checked first (an empty body or a missing parentId triggers the single-root-department error), and only then the name requirement.

Errors

HTTP Code Description
422 BITRIX_ERROR name not provided, or an attempt to create a second root department, or 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