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

List reference records

GET /v1/statuses

Returns CRM reference 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
order object — Sorting: ?order[sort]=asc
filter object — Exact match and $in (IN set) only, on fields id, entityId, statusId, name, sort, semantics, categoryId. Operators (>, >=, <, <=, !, %, $ne, $contains, $nin) and other fields (for example color) are not supported — you get 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 Reference type (DEAL_STAGE, SOURCE, CONTACT_TYPE, etc.)
data[].statusId string Symbolic value code
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 references 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 reference without semantics
data[].extra object/null Additional data for the stage references DEAL_STAGE, QUOTE_STATUS, DEAL_STAGE_N — nested keys SEMANTICS and COLOR. Read-only, absent on other references

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 or unsupported field in the filter. Filter by exact match or $in on id, entityId, statusId, name, sort, semantics, categoryId
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING No API key provided

Full list of errors — Errors.

See also