# Pipelines

Universal management of CRM pipelines for any entity type: deals, smart processes, and others. Each pipeline holds its own set of stages. Unlike [sales pipelines](/docs/entities/deal-categories), this endpoint works for all CRM types through a single path.

Bitrix24 API: `crm.category.*`
Scope: `crm`

The path contains the dynamic parameter `:entityTypeId` — the CRM entity type ID. For deals it is `2`, for invoices `31`, for smart processes it is the value from `GET /v1/smart-processes`. The main deal pipeline is available here under id `0`.

## Operations

- [Create pipeline](./categories/create.md) — `POST /v1/categories/:entityTypeId`
- [List pipelines](./categories/list.md) — `GET /v1/categories/:entityTypeId`
- [Get pipeline](./categories/get.md) — `GET /v1/categories/:entityTypeId/:id`
- [Update pipeline](./categories/update.md) — `PATCH /v1/categories/:entityTypeId/:id`
- [Delete pipeline](./categories/delete.md) — `DELETE /v1/categories/:entityTypeId/:id`
- [Pipeline fields](./categories/fields.md) — `GET /v1/categories/:entityTypeId/fields`

## Key fields

| Field | Description |
|------|---------|
| `id` | Pipeline ID. For deals the main pipeline has id `0` |
| `entityTypeId` | CRM entity type ID, mirrors the path parameter |
| `name` | Pipeline name. Required on creation |
| `sort` | Sort order |
| `isDefault` | Marks the main pipeline of the type |

Full field list — [`GET /v1/categories/:entityTypeId/fields`](./categories/fields.md). Pipeline stages are fetched separately: `GET /v1/statuses?filter[entityId]=DEAL_STAGE_{id}`.

## What to know before you start

1. A pipeline defines its own set of stages: they are requested separately via `GET /v1/statuses`. The pipeline itself stores only the name and sort order.
2. A single `name` field is enough to create one. Without it the response is `422` with the message `Field 'NAME' is required.`
3. Deals `2`, invoices `31`, and smart processes are supported. Quotes `7` have no pipelines — the request returns `422` with a message about the unsupported entity. The reserved ids `2` and `31` work here, unlike in `/v1/items`.
4. **The `code` and `isDefault` fields are read-only.** Sending either of them in the body on creation or update returns `400` with the code `READONLY_FIELD`, and the message names the specific field. The writable fields are `name` and `sort`. The type's main pipeline is assigned in the Bitrix24 interface.
5. `GET /v1/categories/:entityTypeId` returns the full list of pipelines for the type without filtering: the `filter`, `select`, and `order` parameters are accepted without error but have no effect.

## Typical workflow

1. Determine the CRM entity type: for deals `entityTypeId` equals `2`, for a smart process it is the value from [`GET /v1/smart-processes`](/docs/entities/smart-processes/list).
2. Review the existing pipelines of the type: [`GET /v1/categories/2`](./categories/list.md).
3. Create a new one or update an existing one: [`POST /v1/categories/2`](./categories/create.md) / [`PATCH /v1/categories/2/:id`](./categories/update.md).
4. Request the stages of the pipeline you need: `GET /v1/statuses?filter[entityId]=DEAL_STAGE_{id}`.

## Limits

| Limit | Value |
|-------|----------|
| Filtering and pagination | not supported — the list for a type is returned in full |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Sales pipelines](/docs/entities/deal-categories)
- [Stages and statuses](/docs/entities/statuses)
- [Smart process types](/docs/entities/smart-processes)
- [Entity reference](/docs/entities-index)