For AI agents: markdown of this page — /docs-content-en/entities/categories.md documentation index — /llms.txt

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, 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.

Create a pipeline

POST /v1/categories/:entityTypeId

Creates a new pipeline for the specified CRM entity type. Fields are passed flat at the root of the JSON — without a fields wrapper.

Parameters

Parameter Type Required Description
entityTypeId (path) number yes CRM entity type ID. 2 for deals, 31 for invoices, for a smart process — the value from GET /v1/smart-processes

Request fields (body)

Field Bitrix24 Type Required Description
name name string yes Pipeline name
sort sort number no Sort order among the pipelines of this type

Examples

In the examples entityTypeId = 2 (deals) — replace with the type you need.

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/categories/2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partners pipeline",
    "sort": 500
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/categories/2" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partners pipeline",
    "sort": 500
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Partners pipeline',
    sort: 500,
  }),
})

const { success, data } = await res.json()
console.log('Pipeline ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Partners pipeline',
    sort: 500,
  }),
})

const { success, data } = await res.json()

Response fields

Returns the full object of the created pipeline with the assigned id.

Field Type Description
id number Identifier of the created pipeline
entityTypeId number CRM entity type ID, same as the path parameter
name string Pipeline name
sort number Sort order
isDefault boolean Whether this is the type's main pipeline
originId string External source identifier, empty string when absent
originatorId string External system identifier, empty string when absent

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 15,
    "name": "Partners pipeline",
    "sort": 500,
    "entityTypeId": 2,
    "isDefault": false,
    "originId": "",
    "originatorId": ""
  }
}

Error response example

422 — required field name not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Field 'NAME' is required."
  }
}

Errors

HTTP Code Description
400 READONLY_FIELD A read-only field was sent — code or isDefault. The message names the specific field
422 BITRIX_ERROR Required field name not provided — message Field 'NAME' is required.
404 ENTITY_NOT_FOUND entityTypeId does not match an existing type — message Smart process not found
422 BITRIX_ERROR Entity type does not support pipelines, for example quotes 7 — message CRM Quote entity is not supported
403 SCOPE_DENIED API key lacks the crm scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The code and isDefault fields are read-only. Sending code or isDefault in the request body returns 400 READONLY_FIELD — remove these fields from your request. The type's main pipeline is assigned in the Bitrix24 interface.

See also