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

Smart process item fields

GET /v1/items/:entityTypeId/fields

Returns a description of all fields for the given smart process type, including user fields (ufCrmN_*) and parent references (parentIdN).

The field set depends on entityTypeId — each smart process type has its own user fields.

Examples

In the examples entityTypeId = 156 — replace it with your smart process ID.

curl — personal key

Terminal

curl -X GET https://vibecode.bitrix24.com/v1/items/156/fields \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal

curl -X GET https://vibecode.bitrix24.com/v1/items/156/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/items/156/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/items/156/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

The label and description field captions are returned in English, while the ones the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language.

Field	Type	Read-only	Description
`id`	number	yes	Item ID
`title`	string		Name
`xmlId`	string		External code
`stageId`	string		Stage. Format: `DT{typeId}_{catId}:{stage}`
`categoryId`	number		Pipeline ID. List: `GET /v1/categories/:entityTypeId`
`assignedById`	number		Responsible person. List: `GET /v1/users`
`companyId`	number		Company ID. Search: `GET /v1/companies`. Requires the smart process to have the "Client" block enabled, otherwise `400 CLIENT_BLOCK_DISABLED`
`contactId`	number		Contact ID. Search: `GET /v1/contacts`. Requires the smart process to have the "Client" block enabled, otherwise `400 CLIENT_BLOCK_DISABLED`
`contactIds`	array		Linked contacts. Send the full list — the binding set is replaced, not merged. Requires the smart process to have the "Client" block enabled, otherwise `400 CLIENT_BLOCK_DISABLED`
`opportunity`	number		Amount. Stored only on types with product rows enabled (`isLinkWithProductsEnabled: true`); a request with an explicit `isManualOpportunity: true` on a type without them is refused with `422 AMOUNT_NOT_APPLIED` instead of a false success
`currencyId`	string		Currency. List: `GET /v1/currencies`
`opened`	boolean		Available to everyone
`begindate`	datetime		Start date. Stored without time — the passed time is dropped
`closedate`	datetime		Completion date. Stored without time — the passed time is dropped
`sourceId`	string		Source
`sourceDescription`	string		Free-form description of the source
`observers`	array		Observers
`mycompanyId`	number		Own company ID
`createdBy`	number	yes	Creator
`updatedBy`	number	yes	Last editor
`movedBy`	number	yes	Who moved the item to its current stage
`createdTime`	datetime	yes	Creation date
`updatedTime`	datetime	yes	Modification date
`movedTime`	datetime	yes	Stage change date
`isManualOpportunity`	boolean		Amount set manually (`Y`/`N` → `true`/`false`). Stored only on types with product rows enabled (`isLinkWithProductsEnabled: true`); a request with an explicit `isManualOpportunity: true` on a type without them is refused with `422 AMOUNT_NOT_APPLIED` instead of a false success
`isRecurring`	boolean	yes	Recurring item flag
`lastActivityTime`	datetime	yes	Last activity time
`entityTypeId`	number	yes	Smart process type ID. Taken from the path segment, not accepted in the request body
`webformId`	number	yes	ID of the CRM form the item was created from. `0` — the item was not created through a form
`utmSource`	string \| null	yes	`utm_source` tag of the traffic source
`utmMedium`	string \| null	yes	`utm_medium` tag — the traffic channel, for example `cpc` or `email`
`utmCampaign`	string \| null	yes	`utm_campaign` tag — the advertising campaign name
`utmContent`	string \| null	yes	`utm_content` tag — the advertisement content or variant
`utmTerm`	string \| null	yes	`utm_term` tag — the advertisement keyword

Bitrix24 returns the UTM fields in list/get, but for smart process items it accepts them neither in the request body, nor in a filter, nor in sorting — hence the read-only mark, and a request with filter[utmSource] returns an error.

isManualOpportunity and isRecurring arrive from Bitrix24 as the string "Y"/"N" — the platform normalizes them to a JSON boolean on read (and accepts true/false on write for isManualOpportunity), just like opened.

User fields (ufCrmN_*) and parent references (parentIdN) depend on the specific smart process. For enumeration-type fields the response contains an items array with the available values.

Nullability. Many fields arrive as null when not filled in — in particular xmlId, sourceDescription, lastActivityTime and the UTM fields (utmSource/utmMedium/utmCampaign/utmContent/utmTerm, if enabled on the Bitrix24 account). For type-safe clients (TS), declare such fields as T | null.

/fields reflects the live Bitrix24 contract, not the shape of the platform docs. This is a passthrough of the Bitrix24 field schema as is: types arrive in Bitrix24 notation (number, string, boolean, datetime, double, enumeration, crm_contact, crm_status, user and others), the flag is readonly (not isReadOnly), some fields have a label, and there is no separate isRequired or title. Linked contacts are read and written through contactId and contactIds. The platform does not show the contacts service field of the Bitrix24 schema in the reference: no value for it arrives either in the list or in the card, and on write Bitrix24 accepts only an empty array — it rejects any non-empty value with an error from its own data layer. The field would be a promise with nothing behind it. System fields that Bitrix24 returns in list/get but that are not described above (taxValue, previousStageId, lastActivityBy, lastCommunication*) are passed through as-is. The fields in the table above are described by the platform itself, so they carry a human-readable label and description.

Response example

JSON

{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "title": { "type": "string", "readonly": false },
      "stageId": { "type": "string", "readonly": false },
      "begindate": { "type": "datetime", "readonly": false },
      "ufCrm156_custom": { "type": "string", "readonly": false },
      "parentId156": { "type": "number", "readonly": false }
    }
  }
}

Fields arrive inside data.fields. The response object also contains data.products (the product rows schema), data.aggregatable (fields available in aggregation) and data.batch.

Error response example

404 — not found: