لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/categories.md فهرس التوثيق — /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
ParameterentityTypeId (path) Typenumber Requiredyes DescriptionCRM 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
Fieldname Bitrix24name Typestring Requiredyes DescriptionPipeline name
Fieldsort Bitrix24sort Typenumber Requiredno DescriptionSort 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
Fieldid Typenumber DescriptionIdentifier of the created pipeline
FieldentityTypeId Typenumber DescriptionCRM entity type ID, same as the path parameter
Fieldname Typestring DescriptionPipeline name
Fieldsort Typenumber DescriptionSort order
FieldisDefault Typeboolean DescriptionWhether this is the type's main pipeline
FieldoriginId Typestring DescriptionExternal source identifier, empty string when absent
FieldoriginatorId Typestring DescriptionExternal 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
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was sent — code or isDefault. The message names the specific field
HTTP422 CodeBITRIX_ERROR DescriptionRequired field name not provided — message Field 'NAME' is required.
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 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

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