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 dictionaries with stages — `STATUS`, `DEAL_STAGE`, `DEAL_STAGE_N`, `QUOTE_STATUS`. Nested keys `SEMANTICS` and `COLOR`. The `SEMANTICS` values are listed in Dictionary fields. 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: