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

Create a department

POST /v1/departments

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

Request fields (body)

Field 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 no Department head ID. Source: GET /v1/users
sort number no Department order among siblings: a smaller value places it higher in the list. Defaults to 500

You cannot create a second top-level department: a Bitrix24 account supports only one root department. A request without parentId or with parentId: 0 returns 422 BITRIX_ERROR.

headId is not checked for existence. A nonexistent userId in headId is accepted and stored as the department head, and the request returns 201. 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 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
success boolean Always true on success
data object The created department
data.id number ID of the created department
data.name string Name
data.parentId number Parent department ID
data.headId number Head ID. Present only if headId was passed on creation
data.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 — parentId is passed, but the required field name is missing:

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

Fields are checked in order. First, whether parentId is present: without it, including an empty body, the single-root-department error is returned. Then name, and last, whether the parent department exists.

Errors

HTTP Code Description
422 BITRIX_ERROR parentId is missing or set to 0: an attempt to create a second root department
422 BITRIX_ERROR name is missing
422 BITRIX_ERROR parentId references a nonexistent department
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