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

Get pipeline

GET /v1/categories/:entityTypeId/:id

Returns a single pipeline by ID within the specified CRM entity type.

Parameters

Parameter Type Required Description
ParameterentityTypeId (path) Typenumber Requiredyes DescriptionCRM entity type ID. Deals — 2, contacts — 3, companies — 4, invoices — 31, smart processes — from GET /v1/smart-processes
Parameterid (path) Typenumber Requiredyes DescriptionPipeline ID. List: GET /v1/categories/:entityTypeId
Parameterselect (query) Typestring Requiredno DescriptionComma-separated response fields, for example id,name. Without the parameter, all fields are returned. The id field is always returned. Names come from Pipeline fields

Examples

In the examples, entityTypeId = 2, id = 1 — replace with your values.

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

const { success, data } = await res.json()
console.log('Pipeline:', data.name)

JavaScript — OAuth application

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

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionPipeline object
Fielddata.id Typenumber DescriptionPipeline ID. For deals the main pipeline has ID 0
Fielddata.name Typestring DescriptionPipeline name
Fielddata.sort Typenumber DescriptionSort order
Fielddata.entityTypeId Typenumber DescriptionCRM entity type ID, mirrors the path parameter
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_CONTACT. null for the main pipeline and for user-created ones. Contact and company pipelines only
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 if the pipeline has it, and is absent otherwise. 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. Deal pipelines return originId and originatorId, except for the main pipeline (id 0). Contact (3) and company (4) pipelines return isSystem and code. Invoice and smart process pipelines 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

JSON 
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Newest",
    "sort": 100,
    "entityTypeId": 2,
    "isDefault": false,
    "originId": null,
    "originatorId": null
  }
}

The main deal pipeline (id 0) comes without originId and originatorId:

JSON 
{
  "success": true,
  "data": {
    "id": 0,
    "name": "General",
    "sort": 300,
    "entityTypeId": 2,
    "isDefault": true
  }
}

A contact or company pipeline comes back with isSystem and code:

JSON 
{
  "success": true,
  "data": {
    "id": 15,
    "name": "Vendor contacts",
    "sort": 500,
    "entityTypeId": 3,
    "isDefault": false,
    "isSystem": "Y",
    "code": "CATALOG_CONTRACTOR_CONTACT"
  }
}

Error response example

404 — pipeline not found:

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

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo pipeline with the given id in this type
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

Full list of common API errors — Errors.

See also