# Flows and flow tasks

A flow is a shared queue of tasks on one topic: employees submit tasks to the flow, and Bitrix24 passes them to the responsible people and tracks the completion deadline. The methods in this subsection create flows, read them as a list or one at a time, change, delete, enable and disable them, and return flow tasks for each of three statuses.

Bitrix24 API: `tasks.flow.Flow.*`, `tasks.flow.Task.Pending.list`, `tasks.flow.Task.Progress.list`, `tasks.flow.Task.Completed.list`
Scope: `task`

## Operations

- [Create a flow](./flows-create.md) — `POST /v1/tasks/flows`
- [List flows](./flows-list.md) — `GET /v1/tasks/flows`
- [Get a flow](./flows-get.md) — `GET /v1/tasks/flows/:flowId`
- [Update a flow](./flows-update.md) — `PATCH /v1/tasks/flows/:flowId`
- [Delete a flow](./flows-delete.md) — `DELETE /v1/tasks/flows/:flowId`
- [Toggle flow activity](./flows-activate.md) — `POST /v1/tasks/flows/:flowId/activate`
- [List pending flow tasks](./flows-pending.md) — `GET /v1/tasks/flows/:flowId/tasks/pending`
- [List in-progress flow tasks](./flows-progress.md) — `GET /v1/tasks/flows/:flowId/tasks/progress`
- [List completed flow tasks](./flows-completed.md) — `GET /v1/tasks/flows/:flowId/tasks/completed`

## Key fields

Flow fields in the response are named in camelCase. The full set is in the response of [`GET /v1/tasks/flows/:flowId`](./flows-get.md).

| Field | Description |
|------|----------|
| `id` | Flow ID |
| `name` | Flow name. You cannot create two flows with the same name in one Bitrix24 account |
| `groupId` | ID of the workgroup the flow is bound to. List: [`GET /v1/workgroups`](/docs/entities/workgroups/list) |
| `ownerId` | Flow administrator ID. List: [`GET /v1/users`](/docs/entities/users/list) |
| `plannedCompletionTime` | Time to complete a task, in seconds |
| `distributionType` | How tasks reach assignees: `manually` — a moderator assigns them, `queue` — in turn among employees, `himself` — employees take tasks themselves |
| `responsibleList` | Who receives the tasks: an array of pairs like `["user", "3"]`, where the second element is the employee ID. List: [`GET /v1/users`](/docs/entities/users/list) |
| `active` | `true` — the flow is enabled |
| `demo` | `true` — a Bitrix24 demo flow |

## What to know before you start

1. **Field names differ between the list request and the response.** In the list's `select`, `filter`, `order` and `group`, fields are uppercase: `ID`, `NAME`, `ACTIVE`. In create and update request bodies and in the response, they are camelCase: `id`, `name`, `active`.
2. **Creation needs four fields:** `name`, `plannedCompletionTime`, `distributionType` and `responsibleList`. If any of them is missing, the flow is not created and the response is `422 BITRIX_ERROR`.
3. **A flow without `groupId` gets a new workgroup** with the same name. When the flow is deleted, the group stays in the Bitrix24 account.
4. **An update resets settings that are missing from the body.** The description, deadline rules, review of completed tasks and notifications not passed in `PATCH` revert to their defaults. The completion time, distribution, responsible people and group are kept.
5. **Toggling activity does not take a target state.** Each call switches the state to the opposite one, and the response is always `true`. The current state is the flow's `active` field.
6. **Flow tasks are split by status.** Pending tasks have not been started yet, in-progress tasks have been started, and completed tasks were closed within the last `days` days. A task moves from one list to another when its status changes.
7. **Methods respond differently to a flow that does not exist.** Get, update, delete and activity toggle return `422 BITRIX_ERROR`, while the task lists return `200` with an empty list, as for a flow with no tasks.
8. **A read-only key can read flows and their tasks.** With such a key, create, update, delete and activity toggle return `403 WRITE_BLOCKED_READONLY_KEY`.

## Typical scenario

1. Find the responsible people: [`GET /v1/users`](/docs/entities/users/list).
2. Create a flow: [`POST /v1/tasks/flows`](./flows-create.md).
3. Disable the flow or enable it again: [`POST /v1/tasks/flows/:flowId/activate`](./flows-activate.md), and check the state in [`GET /v1/tasks/flows/:flowId`](./flows-get.md).
4. Monitor the workload: [pending](./flows-pending.md), [in-progress](./flows-progress.md) and [completed](./flows-completed.md) flow tasks.

## Limits

| Limit | Value |
|-------|----------|
| Pagination | One page per call, up to 50 records per page. To get the next page, repeat the request with `start` increased by 50: any `start` from `0` to `49` returns the first page. Pages are not loaded automatically |
| Request rate | Common API limits — [Limits and optimization](/docs/optimization) |

## See also

- [Tasks](/docs/entities/tasks)
- [Take task](/docs/entities/tasks/take)
- [Flow form](/docs/chats/service/flow-form)
- [Workgroups](/docs/entities/workgroups)
- [Employees](/docs/entities/users)