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

Search funnels

POST /v1/deal-categories/search

Search sales funnels with filters via the request body — the same interface as for other entities. For simple selections by one or two fields, GET /v1/deal-categories with a query filter also works.

Request fields (body)

Parameter Type Required Default Description
Parameterfilter Typeobject Requiredno Default— DescriptionExact-match and $in (IN set) only, by id, name, sort. Operators (>, >=, <, <=, !, %, $ne, $contains, $nin) and filtering by isLocked / createdAt are not supported — you get 400 UNSUPPORTED_FILTER.
Filtering syntax. Example: { "id": { "$in": [1, 11] } }
Parameterlimit Typenumber Requiredno Default50 DescriptionNumber of records (up to 5000)
Parameteroffset Typenumber Requiredno Default0 DescriptionSkip N records
Parametersort Typestring Requiredno Default— DescriptionSort field. The - prefix means descending: "-sort". The long form "order": { "sort": "desc" } is accepted too
Parameterselect Typestring[] Requiredno Default— DescriptionField selection: ["id", "name", "sort"]

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/deal-categories/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "id": { "$in": [1, 11] } },
    "sort": "sort",
    "select": ["id", "name", "sort"],
    "limit": 3
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/deal-categories/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "id": { "$in": [1, 11] } },
    "sort": "sort",
    "select": ["id", "name", "sort"],
    "limit": 3
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deal-categories/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: { $in: [1, 11] } },
    sort: 'sort',
    select: ['id', 'name', 'sort'],
    limit: 3,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deal-categories/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: { $in: [1, 11] } },
    sort: 'sort',
    select: ['id', 'name', 'sort'],
    limit: 3,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of funnels (fields — see Fields)
Fieldmeta.total Typenumber DescriptionTotal number of funnels matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are records beyond the current page
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 does not rule out the last page.

Response example

The request includes select, so the response contains only the selected fields.

JSON 
{
  "success": true,
  "data": [
    { "id": 1, "name": "Newest", "sort": 100 },
    { "id": 11, "name": "English", "sort": 200 }
  ],
  "meta": { "total": 2, "hasMore": false, "durationMs": 167 }
}

Error response example

400 — a non-filterable field in the filter (isLocked is a visibility toggle, not an equality field):

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "UNSUPPORTED_FILTER: 'isLocked' is not filterable on 'deal-categories'. Its Bitrix24 method (crm.dealcategory.list) filters by exact match only. Filterable: id, name, sort."
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNSUPPORTED_FILTER DescriptionAn operator or a non-filterable field in the filter. Filter by exact match or $in on id, name, sort
HTTP400 CodeINVALID_PARAMS DescriptionRequest field validation failed
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
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 common API errors, see Errors.

See also