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

Search dictionary records

POST /v1/statuses/search

Search CRM dictionary records with filtering. Similar to GET /v1/statuses, but conditions are passed in the request body — this lets you set several conditions at once. The filter works by exact match only.

Request fields (body)

Parameter Type Default Description
filter object — Filtering by GET /v1/statuses/fields fields. Exact match only. Fields: id, entityId, statusId, name, sort, semantics, categoryId.
Filtering syntax. Example: { "entityId": "DEAL_STAGE" }
limit number 50 Number of records, up to 5000
select string[] — Field selection: ["id", "statusId", "name", "sort"]
order object — Sorting: { "sort": "asc" }

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/statuses/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityId": "DEAL_STAGE" },
    "select": ["id", "statusId", "name", "sort", "semantics"],
    "order": { "sort": "asc" }
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/statuses/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityId": "DEAL_STAGE" },
    "select": ["id", "statusId", "name", "sort", "semantics"],
    "order": { "sort": "asc" }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityId: 'DEAL_STAGE' },
    select: ['id', 'statusId', 'name', 'sort', 'semantics'],
    order: { sort: 'asc' },
  }),
})

const { success, data, meta } = await res.json()
console.log('Stages in pipeline:', meta.total)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityId: 'DEAL_STAGE' },
    select: ['id', 'statusId', 'name', 'sort', 'semantics'],
    order: { sort: 'asc' },
  }),
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of dictionary records. Without select, an element contains all fields — see Dictionary fields
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit
meta.durationMs number Request duration in milliseconds

The meta fields sit next to data, not inside it. Pages must be walked by meta.hasMore: a data length equal to limit does not rule out the last page.

Response example

JSON 
{
  "success": true,
  "data": [
    { "id": 101, "statusId": "NEW", "name": "New", "sort": 10, "semantics": null },
    { "id": 111, "statusId": "WON", "name": "Deal won", "sort": 60, "semantics": "S" },
    { "id": 113, "statusId": "LOSE", "name": "Deal lost", "sort": 70, "semantics": "F" }
  ],
  "meta": {
    "total": 8,
    "hasMore": false,
    "durationMs": 2243
  }
}

Error response example

400 — filter by an unsupported field:

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "'foo' is not filterable on 'statuses'. Filters by exact match only. Filterable: id, entityId, statusId, name, sort, semantics, categoryId."
  }
}

Errors

HTTP Code Description
400 UNSUPPORTED_FILTER Filter by a field outside the filterable list or with a non-exact condition
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING No API key provided

Full list of errors — Errors.

Known specifics

Filter — exact match by a single value. The filter selects records whose field is exactly equal to the given value. Comparison operators $gte, $lt and the like return 400 UNSUPPORTED_FILTER. Multiple-value $in is not supported by the dictionary method.

select limits response fields. With select, each data element contains only the listed fields. Without select, all record fields are returned, including the nested extra object of stage dictionaries.

See also