List funnels

GET /v1/categories/:entityTypeId

Returns the funnels of the specified CRM entity type.

Parameters

Examples

The examples use entityTypeId = 2 (deals); replace it with the type you need.

curl — personal key

curl -X GET https://vibecode.bitrix24.com/v1/categories/2 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl -X GET https://vibecode.bitrix24.com/v1/categories/2 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
console.log(`Pipelines: ${data.length}`)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

The field set depends on the entity type. Deals return originId and originatorId, except for the main pipeline (id 0). Contacts (3) and companies (4) return isSystem and code. Invoices and smart processes return only the common fields. The createdDate field from the pipeline schema is not returned for any type, even when listed in select.

For deals (entityTypeId = 2), get the stages of the main pipeline (id = 0) from GET /v1/statuses?filter[entityId]=DEAL_STAGE and the stages of an additional pipeline (id = N) from GET /v1/statuses?filter[entityId]=DEAL_STAGE_{id} (for example, id = 1 → DEAL_STAGE_1). This deal-stage directory naming rule does not apply to invoices or smart processes.

Response example

The response always contains meta. Additional deal funnels have originId and originatorId; the main funnel (id 0) does not:

{
  "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 }
  ],
  "meta": { "total": 3, "hasMore": false }
}

Smart process funnels have a shorter set of fields:

{
  "success": true,
  "data": [
    { "id": 3, "name": "General", "sort": 500, "entityTypeId": 174, "isDefault": true },
    { "id": 23, "name": "Extra pipeline", "sort": 510, "entityTypeId": 174, "isDefault": false }
  ],
  "meta": { "total": 2, "hasMore": false }
}

Company and contact pipelines come back with isSystem and code:

{
  "success": true,
  "data": [
    { "id": 0, "name": "Default pipeline", "sort": 0, "entityTypeId": 4, "isDefault": true, "isSystem": "Y", "code": null },
    { "id": 17, "name": "Vendors", "sort": 500, "entityTypeId": 4, "isDefault": false, "isSystem": "Y", "code": "CATALOG_CONTRACTOR_COMPANY" }
  ],
  "meta": { "total": 2, "hasMore": false }
}

Error response example

404 — type not found:

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

Errors

For the full list of general API errors, see Errors.

Known specifics

Sort and filter by name on the client side. The server filters pipelines only by code and always sorts them by the sort field in ascending order. To find a pipeline by name, search data: data.filter(c => c.name === 'Sales').

Find a system pipeline by code, not by id. Bitrix24 sets the code of a system pipeline, such as CATALOG_CONTRACTOR_COMPANY, and it is the same across Bitrix24 accounts. The id of the same system pipeline differs from one account to another.

Paging is relative to the full list for the type. meta.total reports how many funnels the type has in total and does not change with limit or offset — walk the list until meta.hasMore is false.

See also

• Search funnels
• Get funnel
• Create funnel
• Funnel fields
• Smart process types
• Stages and statuses
• Entity API