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

Sales pipelines

Sales pipelines (deal categories). Each pipeline has its own set of stages.

Bitrix24 API: crm.dealcategory.* Scope: crm

Pipeline stages: GET /v1/statuses?filter[entityId]=DEAL_STAGE_{categoryId}

The main pipeline with id 0 is not returned by /v1/deal-categories and is not addressable by id here — use the universal endpoint /v1/categories/2 for it.

Create a pipeline

POST /v1/deal-categories

Creates a new sales pipeline. After creation, add stages via reference data with entityId = DEAL_STAGE_{id}.

Request body parameters

Parameter Type Required Description
name string yes Pipeline name
sort number Sort order

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/deal-categories" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Corporate sales", "sort": 200}'

curl — OAuth application

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

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deal-categories', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Corporate sales', sort: 200 }),
})
const { success, data } = await res.json()

JavaScript — OAuth application

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

Response fields

Field Type Description
success boolean Always true on success
data object The created pipeline with all fields
data.id number Pipeline ID
data.name string Name
data.sort number Sort
data.isLocked boolean Whether the pipeline is locked — unavailable on the current plan
data.createdAt datetime Creation date

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 5,
    "createdAt": "2026-06-01T10:00:00.000Z",
    "name": "Wholesale sales",
    "sort": 200,
    "isLocked": false
  }
}

Error response example

422 — name is missing:

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

Errors

HTTP Code Description
422 BITRIX_ERROR name is missing — message Field 'NAME' is required.
422 BITRIX_ERROR Other Bitrix24 refusals — the reason is in message
403 SCOPE_DENIED The API key lacks the crm scope
401 MISSING_API_KEY The X-Api-Key header is missing

Full list of errors — Errors.

See also