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, each 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
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.

Known specifics

Filter — exact match on 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. A value list ($in or an array) is not supported by the dictionary method on any field — that filter is rejected with 400 UNSUPPORTED_FILTER. Pass a single value and request several values in separate calls or via POST /v1/batch.

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 the STATUS, DEAL_STAGE, DEAL_STAGE_N, QUOTE_STATUS dictionaries.

See also