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

CRM dictionaries

Deal stages, sources, contact types, industries and other classifiers. The central entity for enum values across the entire CRM.

Bitrix24 API: crm.status.* Scope: crm

To fetch a specific type use the filter: ?filter[entityId]=DEAL_STAGE

Create dictionary record

POST /v1/statuses

Creates a new record in a CRM dictionary. Required fields: entityId, statusId, name.

Request body parameters

Parameter Type Required Description
entityId string yes Dictionary type (DEAL_STAGE, SOURCE, etc.)
statusId string yes Symbolic code of the value
name string yes Name
sort number Sort order
color string Color in HEX, e.g. #22B9FF. The # may be omitted
semantics string Semantics: S — success, F — failure

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/statuses" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityId": "SOURCE", "statusId": "PARTNER", "name": "Partner", "sort": 50}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/statuses" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entityId": "SOURCE", "statusId": "PARTNER", "name": "Partner", "sort": 50}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ entityId: 'SOURCE', statusId: 'PARTNER', name: 'Partner', sort: 50 }),
})
const { success, data } = await res.json()
console.log('ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ entityId: 'SOURCE', statusId: 'PARTNER', name: 'Partner', sort: 50 }),
})
const { success, data } = await res.json()

Response fields

Field Type Description
id number Record ID
entityId string Dictionary type
statusId string Symbolic code
name string Name
nameInit string/null Original name
sort number Sort order
system boolean System value. Read-only
categoryId number/null Pipeline ID. Set for dictionaries of the form DEAL_STAGE_N, otherwise 0 or null
color string/null Color in HEX with a leading #
semantics string/null Semantics: S — success, F — failure. null — an in-progress stage or a dictionary without semantics
extra object/null Additional data for stage dictionaries DEAL_STAGE, QUOTE_STATUS, DEAL_STAGE_N — nested keys SEMANTICS and COLOR. Read-only, absent for other dictionaries

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 801,
    "entityId": "SOURCE",
    "statusId": "PARTNER",
    "name": "Partner",
    "nameInit": null,
    "sort": 50,
    "system": false,
    "categoryId": 0,
    "color": null,
    "semantics": null
  }
}

Error response example

422 — duplicate code:

JSON 
{
  "success": false,
  "error": { "code": "BITRIX_ERROR", "message": "The specified status ID already exists." }
}

Errors

HTTP Code Description
422 BITRIX_ERROR Bitrix24 error (duplicate statusId, etc.)
403 SCOPE_DENIED API key does not have the crm scope
401 TOKEN_MISSING API key was not provided

Full list of errors — Errors.

See also