لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/departments.md فهرس التوثيق — /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)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionDepartment name
FieldparentId Typenumber Requiredyes DescriptionParent department ID. Parent list: GET /v1/departments. For a top-level department use parentId: 1
FieldheadId Typenumber Requiredno DescriptionDepartment head ID. Source: GET /v1/users
Fieldsort Typenumber Requiredno DescriptionDepartment 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created department
Fielddata.id Typenumber DescriptionID of the created department
Fielddata.name Typestring DescriptionName
Fielddata.parentId Typenumber DescriptionParent department ID
Fielddata.headId Typenumber DescriptionHead ID. Present only if headId was passed on creation
Fielddata.sort Typenumber DescriptionSort 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
HTTP422 CodeBITRIX_ERROR DescriptionparentId is missing or set to 0: an attempt to create a second root department
HTTP422 CodeBITRIX_ERROR Descriptionname is missing
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