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
Parameterfilter Typeobject Default— DescriptionFilter by the fields from GET /v1/statuses/fields. Exact match only. Fields: id, entityId, statusId, name, sort, semantics, categoryId.
Filtering syntax. Example: { "entityId": "DEAL_STAGE" }
Parameterlimit Typenumber Default50 DescriptionNumber of records, up to 5000
Parameterselect Typestring[] Default— DescriptionField selection: ["id", "statusId", "name", "sort"]
Parameterorder Typeobject Default— DescriptionSorting: { "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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of dictionary records. Without select, each element contains all fields — see Dictionary fields
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds

The meta fields sit next to data, not inside it. Page through the results using meta.hasMore: a data length equal to limit can still be 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
HTTP400 CodeUNSUPPORTED_FILTER DescriptionFilter by a field outside the filterable list or with a non-exact condition
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of errors, see 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. To match several values, make separate calls or use 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