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

List of dictionaries

GET /v1/statuses

Returns CRM dictionary records. Use filter[entityId] to select a specific type.

Parameters

Parameter Type Default Description
limit number 50 Number of records (up to 5000). When limit > 50, auto-pagination applies
offset number 0 Skip N records
select string — Field selection: ?select=id,name,entityId
sort string — Sorting via the short syntax: ?sort=-sort, the minus means descending
order object — Sorting: ?order[sort]=asc
filter object — Exact match on a single value only, for the fields id, entityId, statusId, name, sort, semantics, categoryId. A value list ($in or an array) is not supported on any field: the dictionary method does not accept one, so such a filter is rejected immediately with 400 UNSUPPORTED_FILTER — pass a single value and request several values in separate calls or via POST /v1/batch. Operators (>, >=, <, <=, !, %, $ne, $contains, $nin) and other fields (for example color) are not supported — also 400 UNSUPPORTED_FILTER.
Filtering syntax. Example: ?filter[entityId]=DEAL_STAGE

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/statuses?filter[entityId]=DEAL_STAGE&order[sort]=asc" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/statuses?filter[entityId]=DEAL_STAGE&order[sort]=asc" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses?filter[entityId]=DEAL_STAGE&order[sort]=asc', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { success, data, meta } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses?filter[entityId]=DEAL_STAGE&order[sort]=asc', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { success, data, meta } = await res.json()

Response fields

Field Type Description
data[].id number Record ID
data[].entityId string Dictionary type (DEAL_STAGE, SOURCE, CONTACT_TYPE, etc.)
data[].statusId string Symbolic code of the value
data[].name string Name
data[].nameInit string/null Original name
data[].sort number Sort order
data[].system boolean System value. Read-only
data[].categoryId number/null Pipeline ID. Populated for dictionaries of the form DEAL_STAGE_N, otherwise 0 or null
data[].color string/null Color in HEX with a leading #
data[].semantics string/null Semantics: S — success, F — failure. null — an in-progress stage or a dictionary without semantics
data[].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": 101,
      "entityId": "DEAL_STAGE",
      "statusId": "NEW",
      "name": "New",
      "nameInit": "New",
      "sort": 10,
      "system": true,
      "categoryId": null,
      "color": "#39A8EF",
      "semantics": null,
      "extra": { "SEMANTICS": "process", "COLOR": "#39A8EF" }
    },
    {
      "id": 111,
      "entityId": "DEAL_STAGE",
      "statusId": "WON",
      "name": "Deal won",
      "nameInit": "Deal won",
      "sort": 60,
      "system": true,
      "categoryId": null,
      "color": "#7BD500",
      "semantics": "S",
      "extra": { "SEMANTICS": "success", "COLOR": "#7BD500" }
    }
  ],
  "meta": { "total": 12, "hasMore": false }
}

Error response example

400 — an operator or unsupported field in the filter:

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "UNSUPPORTED_FILTER: 'color' is not filterable on 'statuses'. Its Bitrix24 method (crm.status.list) filters by exact match only. Filterable: id, entityId, statusId, name, sort, semantics, categoryId."
  }
}

Errors

HTTP Code Description
400 UNSUPPORTED_FILTER An operator, an unsupported field, or a value list. Filter by exact match on a single value — on the fields id, entityId, statusId, name, sort, semantics, categoryId
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING No API key provided
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of errors — Errors.

See also