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

Funnel fields

GET /v1/categories/:entityTypeId/fields

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

Parameters

Parameter Type Description
ParameterentityTypeId (path) Typenumber DescriptionCRM entity type ID. Deals — 2, invoices — 31, smart processes — from GET /v1/smart-processes

Examples

The examples use entityTypeId = 2 (deals); replace it 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 application

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 application

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

The response contains the funnel field schema and available operations.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionFunnel schema and available operations
Fielddata.fields Typeobject DescriptionDictionary of funnel fields: the key is the field name, and the value is an object describing it. The dictionary fields are listed below
Fielddata.fields.<field> Typeobject DescriptionObject describing one field: type, readonly, label, and description
Fielddata.batch Typearray DescriptionWrite operations available in batch calls: create, update, delete

Funnel field schema

The table lists the value types of the fields described in data.fields.

Field Type RO Description
Fieldid Typenumber RORO DescriptionFunnel ID. For deals, the main funnel has ID 0
FieldentityTypeId Typenumber RORO DescriptionCRM entity type ID, mirrors the path parameter
Fieldname Typestring RO DescriptionFunnel name. Required on creation
Fieldsort Typenumber RO DescriptionSort order
FieldisDefault Typeboolean RORO DescriptionMarks the main funnel. Read-only — a write is rejected with 400 READONLY_FIELD
Fieldcode Typestring RORO DescriptionSymbolic code of a system funnel, for example CATALOG_CONTRACTOR_CONTACT. Returned only for contact and company funnels; filter[code] filters by it. Read-only — a write is rejected with 400 READONLY_FIELD
FieldisSystem Typestring RO DescriptionSystem funnel: Y or N, as Bitrix24 returns it. Returned only for contact and company funnels. Passed to Bitrix24 as is: Bitrix24 does not allow creating a funnel with Y and responds with 422 BITRIX_ERROR; on update, the field is ignored
FieldcreatedDate Typedatetime RORO DescriptionCreation date. Bitrix24 does not return it: the field is not returned for any funnel type, even when requested in select, and the schema marks it notReturned: true
FieldoriginId Typestring RORO DescriptionExternal identifier of the funnel in the system it was imported from. Read-only — a write is rejected with 400 READONLY_FIELD: Bitrix24 does not store the value
FieldoriginatorId Typestring RORO DescriptionSource system 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 },
      "isSystem": { "type": "string", "readonly": false },
      "createdDate": { "type": "datetime", "readonly": true, "notReturned": 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
HTTP404 CodeENTITY_NOT_FOUND DescriptionentityTypeId does not match an existing CRM type
HTTP422 CodeBITRIX_ERROR DescriptionThe CRM type does not support funnels. Quotes (type 7) have no funnels
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 common API errors, see Errors.

See also