# 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) |
| `sort` | Sort order of the department among its siblings (integer, ascending) |

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

## What you need 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 the service top 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 point above).
3. **`headId` is an employee ID, not a department ID, and is NOT checked for existence.** Any employee in your Bitrix24 account can be assigned as head. Bitrix24 does not validate `headId`: a nonexistent ID is accepted and stored as a dangling reference (the request returns `201`/`200`). Only `parentId` is validated. Confirm the user exists via [`GET /v1/users`](/docs/entities/users).
4. **`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.
5. **Deleting a department with children is not forbidden and rebuilds the tree.** Bitrix24 deletes the department even when it has child departments or employees: direct child departments are re-parented onto the deleted department's parent with their `sort` reassigned. To control the resulting structure, move the child departments and employees before deleting.

## Typical scenario

1. Fetch the current structure: [`GET /v1/departments`](./departments/list.md) — see the tree by `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: via [`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 row-exactly (`offset=7` starts at the 8th record) |
| `order` parameter | not applied — the result order is fixed |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch). `create`, `update`, `delete` are supported |
| Rate limit | shared across the Vibe API — see [Limits and optimization](/docs/optimization) |

## See also

- [Entity API](/docs/entity-api) — common principles for working with entities
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch) — bulk operations
- [Employees](/docs/entities/users) — assignment to departments and finding heads
- [Entity reference](/docs/entities-index)