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

Search pipelines

POST /v1/deal-categories/search

Search sales pipelines with filters via the request body — a unified interface with the 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 Default Description
filter object — Exact-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] } }
limit number 50 Number of records (up to 5000)
offset number 0 Skip N records
order object — Sorting: { "sort": "asc" }
select string[] — Field 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] } },
    "order": { "sort": "asc" },
    "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] } },
    "order": { "sort": "asc" },
    "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] } },
    order: { sort: 'asc' },
    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] } },
    order: { sort: 'asc' },
    select: ['id', 'name', 'sort'],
    limit: 3,
  }),
})

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

Response fields

Field Type Description
data array Array of pipelines (fields — see Fields)
meta.total number Total number of pipelines matching the filter
meta.hasMore boolean Whether there are records beyond the current page
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

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
400 UNSUPPORTED_FILTER An operator or a non-filterable field in the filter. Filter by exact match or $in on id, name, sort
400 INVALID_PARAMS Request field validation failed
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

See also