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

Pipeline fields

GET /v1/categories/:entityTypeId/fields

Returns the pipeline field schema for the specified CRM entity type: names, types, and the read-only flag.

Parameters

Parameter Type Description
entityTypeId (path) number CRM entity type ID. Deals — 2, invoices — 31, smart processes — from GET /v1/smart-processes

Examples

In the examples entityTypeId = 2 (deals) — replace with the type you need.

curl — personal key

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

curl — OAuth app

Terminal 
curl -X GET https://vibecode.bitrix24.com/v1/categories/2/fields \
  -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/fields', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)

JavaScript — OAuth app

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

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

Response fields

Field Bitrix24 Type RO Description
id id number RO Pipeline ID. For deals the main pipeline has ID 0
entityTypeId entityTypeId number RO CRM entity type ID, mirrors the path parameter
name name string Pipeline name. Required on creation
sort sort number Sort order
isDefault isDefault boolean RO Marks the main pipeline. Read-only — a write is rejected with 400 READONLY_FIELD
code code string RO Symbolic code. Read-only — a write is rejected with 400 READONLY_FIELD. Not returned in list, get, and search responses
createdDate createdDate datetime RO Creation date. Not returned in list and get responses
originId ORIGIN_ID string RO Identifier of the pipeline in the system it was imported from. Read-only — a write is rejected with 400 READONLY_FIELD: Bitrix24 does not store the value
originatorId ORIGINATOR_ID string RO System that is the source of the external binding. Read-only — a write is rejected with 400 READONLY_FIELD: Bitrix24 does not store the value

The batch field lists the operations available in a batch request: create, update, delete.

The label captions come straight from the Bitrix24 account, so they are returned in the account language — and for some fields they repeat the Bitrix24 field name, like ORIGIN_ID in the example below. Request headers do not switch the language.

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "entityTypeId": { "type": "number", "readonly": true },
      "name": { "type": "string", "readonly": false },
      "sort": { "type": "number", "readonly": false },
      "isDefault": { "type": "boolean", "readonly": true },
      "code": { "type": "string", "readonly": true },
      "createdDate": { "type": "datetime", "readonly": true },
      "originId": { "type": "string", "readonly": true, "label": "ORIGIN_ID" },
      "originatorId": { "type": "string", "readonly": true, "label": "ORIGINATOR_ID" }
    },
    "batch": ["create", "update", "delete"]
  }
}

Error response example

404 — type not found:

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

Errors

HTTP Code Description
404 ENTITY_NOT_FOUND entityTypeId does not match an existing CRM type
422 BITRIX_ERROR The CRM type does not support pipelines. Quotes (type 7) have no pipelines
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING The API key has no configured tokens
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

See also