# 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 entity 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 contacts `3`, for companies `4`, for invoices `31`, and 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`
- [Search pipelines](./categories/search.md) — `POST /v1/categories/:entityTypeId/search`
- [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 |
| `code` | Symbolic code of a system pipeline, for example `CATALOG_CONTRACTOR_CONTACT`. Contact and company pipelines only; `filter[code]` filters by it |

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. The `name` field alone is enough to create a pipeline. Without it the response is `422` with the message `Field 'NAME' is required.`
3. Deals `2`, contacts `3`, companies `4`, 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. **Only `name` and `sort` are writable.** The other fields — `id`, `entityTypeId`, `isDefault`, `code`, `createdDate`, `originId`, and `originatorId` — are read-only: sending any of them in the body on creation or update returns `400` with the code `READONLY_FIELD`, and the message names the specific field. `isSystem` is passed to Bitrix24 as is: Bitrix24 does not allow creating a pipeline with `isSystem: "Y"` and returns `422 BITRIX_ERROR`; on update, the field is ignored. The type's main pipeline is assigned in the Bitrix24 interface.
5. **Pipelines can be filtered only by code.** `select`, `limit`, and `offset` do work: `select` narrows the field set, `limit` and `offset` page through the output. Filtering works only by `code`, as an exact match, and only contact and company pipelines have a code. Other `filter` fields, as well as `sort` and `order`, are accepted but have no effect — pipelines are always ordered by the `sort` field. A field name the pipeline does not have is rejected: `400 UNKNOWN_FILTER_FIELD` in `filter`, `400 UNKNOWN_SORT_FIELD` in `sort` or `order`. To select by name, filter the returned list on the client side.

## Typical scenario

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 |
|-------|----------|
| Pagination | `limit` — `50` by default, `5000` maximum. `offset` — how many pipelines to skip from the start of the list |
| Filtering and sorting | `filter` works only by `code`; `sort` and `order` have no effect |
| 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)
- [API reference](/docs/api-reference)