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

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
ParameterentityTypeId (path) Typenumber Requiredyes DescriptionCRM entity type ID. 2 for deals, 3 for contacts, 4 for companies, 31 for invoices; for a smart process, the value from GET /v1/smart-processes

Request fields (body)

Field Bitrix24 Type Required Description
Fieldname Bitrix24name Typestring Requiredyes DescriptionPipeline name
Fieldsort Bitrix24sort Typenumber Requiredno DescriptionSort order among the pipelines of this type

Examples

The examples use entityTypeId = 2 (deals); replace it 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
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata Typeobject DescriptionThe created pipeline
Fielddata.id Typenumber DescriptionIdentifier of the created pipeline
Fielddata.entityTypeId Typenumber DescriptionCRM entity type ID, same as the path parameter
Fielddata.name Typestring DescriptionPipeline name
Fielddata.sort Typenumber DescriptionSort order
Fielddata.isDefault Typeboolean DescriptionWhether this is the type's main pipeline
Fielddata.originId Typestring | null DescriptionExternal source identifier. null for pipelines with no external binding. Deal pipelines only
Fielddata.originatorId Typestring | null DescriptionExternal system identifier. null for pipelines with no external binding. Deal pipelines only
Fielddata.isSystem Typestring DescriptionSystem pipeline: N for one created through the API. Contact and company pipelines only
Fielddata.code Typestring | null DescriptionSymbolic code of a system pipeline. null for one created through the API. Contact and company pipelines only

The field set depends on the entity type. For deals, the response includes originId and originatorId; for contacts (3) and companies (4), isSystem and code; for invoices and smart processes, only the common fields. The createdDate field from the pipeline schema is not returned.

Response example

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

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
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was sent: id, entityTypeId, isDefault, code, createdDate, originId or originatorId. The message names the specific field
HTTP422 CodeBITRIX_ERROR DescriptionRequired field name not provided — message Field 'NAME' is required.
HTTP422 CodeBITRIX_ERROR DescriptionisSystem: "Y" was sent — Bitrix24 does not allow creating a system pipeline
HTTP404 CodeENTITY_NOT_FOUND DescriptionentityTypeId does not match an existing type — message Smart process not found
HTTP422 CodeBITRIX_ERROR DescriptionEntity type does not support pipelines, for example, quotes (type 7) — message CRM Quote entity is not supported
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Only name and sort are writable. The other pipeline fields except isSystem are read-only — leave them out of the request body, or the request returns 400 READONLY_FIELD. isSystem goes to Bitrix24, which does not allow creating a pipeline with Y. The type's main pipeline is assigned in the Bitrix24 interface.

See also