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

Search funnels

POST /v1/categories/:entityTypeId/search

Returns the pipelines of the specified CRM entity type. The parameters are passed in the request body rather than in the query string.

The same set of funnels is served by GET /v1/categories/:entityTypeId.

Parameters

Parameter Type Required Description
ParameterentityTypeId (path) Typenumber Requiredyes DescriptionCRM entity type identifier. Deals — 2, contacts — 3, companies — 4, invoices — 31, smart processes — the value from GET /v1/smart-processes

Request fields (body)

Field Type Required Default Description
Fieldlimit Typenumber Requiredno Default50 DescriptionNumber of records, up to 5000
Fieldoffset Typenumber Requiredno Default— DescriptionHow many funnels to skip from the start of the list
Fieldselect Typestring[] Requiredno Default— DescriptionField selection: ["id", "name", "sort"]
Fieldfilter Typeobject Requiredno Default— DescriptionFiltering works only by code, as an exact match: {"code": "CATALOG_CONTRACTOR_COMPANY"}. Only contact and company pipelines have a code. Other filter fields are accepted but do not narrow the result. An unknown field name returns 400 UNKNOWN_FILTER_FIELD; valid names come from GET /v1/categories/:entityTypeId/fields

Examples

In the examples, entityTypeId is 2 (deals). Substitute the type you need.

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/categories/2/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 5 }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/categories/2/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 5 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ limit: 5 }),
})

const { success, data, meta } = await res.json()
console.log(`Pipelines of this type: ${meta.total}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ limit: 5 }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of funnels for the type
Fielddata[].id Typenumber DescriptionFunnel identifier. For the main deal funnel it equals 0
Fielddata[].name Typestring DescriptionFunnel name
Fielddata[].sort Typenumber DescriptionSort order
Fielddata[].entityTypeId Typenumber DescriptionCRM entity type identifier, mirrors the path segment
Fielddata[].isDefault Typeboolean DescriptionMarks the main pipeline of the type
Fielddata[].originId Typestring | null DescriptionExternal identifier. null for pipelines with no external binding. Deal pipelines only
Fielddata[].originatorId Typestring | null DescriptionSource of the external binding. null for pipelines with none. Deal pipelines only
Fielddata[].isSystem Typestring DescriptionSystem pipeline: Y — created by Bitrix24, N — created by a user. Contact and company pipelines only.
Fielddata[].code Typestring | null DescriptionSymbolic code of a system pipeline, for example CATALOG_CONTRACTOR_COMPANY. null for the main pipeline and for user-created ones. Contact and company pipelines only
Fieldmeta.total Typenumber DescriptionNumber of pipelines the type has
Fieldmeta.hasMore Typeboolean DescriptionWhether pipelines remain beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds
Fieldmeta.warnings Typearray DescriptionReturned when select lists a name that is absent from the pipeline schema, or the createdDate field, which Bitrix24 does not return. The request still runs: a field with an unknown name comes back for the pipelines that have it, and is absent for the rest. Each warning is an object with code, field and message, and the code is UNKNOWN_SELECT_FIELD

The field set depends on the entity type. Deals return originId and originatorId, except for the main pipeline — check that a key is present before reading it. Contacts (3) and companies (4) return isSystem and code. Invoices and smart processes return only the common fields.

Response example

JSON 
{
  "success": true,
  "data": [
    { "id": 1, "name": "Newest", "sort": 100, "entityTypeId": 2, "isDefault": false, "originId": null, "originatorId": null },
    { "id": 11, "name": "English", "sort": 200, "entityTypeId": 2, "isDefault": false, "originId": null, "originatorId": null },
    { "id": 0, "name": "General", "sort": 300, "entityTypeId": 2, "isDefault": true },
    { "id": 3, "name": "Partners", "sort": 400, "entityTypeId": 2, "isDefault": false, "originId": null, "originatorId": null },
    { "id": 9, "name": "Tenders", "sort": 500, "entityTypeId": 2, "isDefault": false, "originId": null, "originatorId": null }
  ],
  "meta": {
    "total": 8,
    "hasMore": true,
    "durationMs": 1847
  }
}

Error response example

404 — no CRM type with this entityTypeId:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Smart process not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_DYNAMIC_PARAM DescriptionentityTypeId in the path is not a positive integer
HTTP400 CodeUNKNOWN_FILTER_FIELD Descriptionfilter names a field the pipeline does not have. The message lists the valid names
HTTP400 CodeUNKNOWN_SORT_FIELD Descriptionsort or order names a field the pipeline does not have. The message lists the valid names
HTTP404 CodeENTITY_NOT_FOUND DescriptionentityTypeId does not match an existing CRM type
HTTP422 CodeBITRIX_ERROR DescriptionThe CRM type does not support pipelines. Quotes (type 7) have no pipelines
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 general API errors, see Errors.

Known specifics

The order does not change, and there is no filtering by name. sort and order in the body are accepted, but pipelines always come sorted by the sort field ascending. An unknown field name returns 400 UNKNOWN_SORT_FIELD; valid names come from GET /v1/categories/:entityTypeId/fields. To find a pipeline by name, match its name in the returned array; to get a single known pipeline in full, use GET /v1/categories/:entityTypeId/:id. A system contact or company pipeline is more reliably found by filtering on code: the code is the same across Bitrix24 accounts, while the id differs.

See also