# 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](/docs/entities/users).

Bitrix24 API: `department.*`
Scope: `department`

## Operations

- [Create a department](./departments/create.md) — `POST /v1/departments`
- [List departments](./departments/list.md) — `GET /v1/departments`
- [Get a department](./departments/get.md) — `GET /v1/departments/:id`
- [Update a department](./departments/update.md) — `PATCH /v1/departments/:id`
- [Delete a department](./departments/delete.md) — `DELETE /v1/departments/:id`
- [Search departments](./departments/search.md) — `POST /v1/departments/search`
- [Department fields](./departments/fields.md) — `GET /v1/departments/fields`

## Key fields

| Field | Description |
|------|---------|
| `id` | Department identifier |
| `name` | Department name |
| `parentId` | Parent department ID. For the Bitrix24 account's root department it equals `1` |
| `headId` | Department head ID. Source: [`GET /v1/users`](/docs/entities/users). Caveats — item 4 below |
| `sort` | Sort order of the department among its siblings (integer, ascending) |

Full field list — [`GET /v1/departments/fields`](./departments/fields.md).

## What to know before you start

1. **The department structure is a tree with a single root.** Top-level departments reference the root node via `parentId: 1`. The root node itself is not returned by [`GET /v1/departments`](./departments/list.md) and is not accessible via `GET /v1/departments/:id` — it is an internal service node of the tree. An attempt to create a second top-level department (without `parentId` or with `parentId: 0`) returns HTTP 422 with the message "The company structure must have only one top-level section."
2. **The minimum to create a single department is two fields:** `name` and `parentId`. If `parentId` is omitted, the request is treated as an attempt to create a top-level department (see the item above).
3. **`headId` is a user ID, not a department ID, and is NOT checked for existence.** A nonexistent ID is accepted and saved, and the request returns `201` or `200`. Only `parentId` is validated. Confirm the user exists via [`GET /v1/users`](/docs/entities/users).
4. **`headId` can point to a user account that is not in the employee directory.** A department head can be a user account that [`GET /v1/users`](/docs/entities/users/list) does not return, such as a chatbot. In that case `GET /v1/users/:id` with the `headId` value returns `404 ENTITY_NOT_FOUND`. In the org structure, the head of such a department may differ from `headId`: the `MEMBER_HEAD` role belongs to another employee or is not assigned. Take the current head from the org structure. Your API key needs the `humanresources` scope. Find the department's node in [`GET /v1/humanresources/nodes?type=DEPARTMENT`](/docs/humanresources/nodes/list): its `accessCode` is the letter `D` followed by the department `id`, not the node `id` — department `107` maps to `D107`. Nodes with a different prefix, such as `SN23`, were created in the org structure and are not returned by `GET /v1/departments`. There is no filter by `accessCode`, so page through the list. Then fetch the node with [`GET /v1/humanresources/nodes/:id`](/docs/humanresources/nodes/get): the head is the entry in the `members` array with the `MEMBER_HEAD` role. If there is no such entry, the department has no head assigned.
5. **`sort` controls the order in the list.** The `sort` value is compared between departments at the same level — within the same `parentId`. A smaller value places the department higher in the list.
6. **Deleting a department with children is not forbidden and rebuilds the tree.** The department is deleted even when it has child departments or employees, and its direct child departments move under the deleted department's parent with a new `sort`. To control the resulting structure, move the child departments and employees before deleting the department.

## Typical scenario

1. Fetch the current structure: [`GET /v1/departments`](./departments/list.md) — build the tree from `parentId`.
2. Find a head for the new department: [`GET /v1/users?filter[name]=John`](/docs/entities/users).
3. Create the department: [`POST /v1/departments`](./departments/create.md) with `name`, `parentId`, `headId`.
4. Assign employees to the department: [`PATCH /v1/users/:id`](/docs/entities/users) with the `departmentId` field (array of department IDs).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `offset` parameter | applied per record (`offset=7` starts at the 8th record) |
| `order` and `sort` parameters | not supported — `400 INVALID_SORT_FIELD`, the Bitrix24 account sets the result order |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch). `create`, `update`, `delete` are supported |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Employees](/docs/entities/users)
- [Org structure nodes](/docs/humanresources/nodes)
- [API reference](/docs/api-reference)