Smart process fields

Create, read, update, and delete user fields on smart process items. The smart process type is set in the path by entityTypeId — the public number from the Bitrix24 account's smart process catalog.

Bitrix24 API: userfieldconfig.* Scope: crm, userfieldconfig

Operations

List smart process fields — GET /v1/items/:entityTypeId/userfields
Type catalog — GET /v1/items/:entityTypeId/userfields/types
Get field — GET /v1/items/:entityTypeId/userfields/:id
Create field — POST /v1/items/:entityTypeId/userfields
Update field — PATCH /v1/items/:entityTypeId/userfields/:id
Delete field — DELETE /v1/items/:entityTypeId/userfields/:id

For the built-in smart invoice (entityTypeId=31), the same six operations are also available at /v1/userfields/invoices, with the same suffixes and request bodies.

Getting `entityTypeId`

The smart process type identifier is returned in the response of GET /v1/smart-processes — the entityTypeId field on each element of the data array. For built-in CRM entities (deals, leads, contacts, companies, quotes, requisites), use the CRM entity fields section — it works with a fixed set of entities via the :entity name.

In responses from the userfield endpoints of regular smart processes, entityId uses the CRM_<typeId> format, where typeId is the smart process's internal sequential identifier. This does not match the public entityTypeId in the request path. The built-in smart invoice (entityTypeId=31) uses a special entityId=CRM_SMART_INVOICE. Field names in userfield responses use the Bitrix24 UF_ + entityId + _* format: UF_CRM_<typeId>_* for a regular smart process, UF_CRM_SMART_INVOICE_* for the smart invoice. The same prefix is required in fieldName when you create a field. In the item schema and in requests to items, the same field is named ufCrm<typeId>_* — for example UF_CRM_3_1628508847 and ufCrm3_1628508847. The working name for reading and writing values comes from GET /v1/items/{entityTypeId}/fields, and the value formats by type are in User fields (UF).

Key scope requirements

Reading and writing smart process fields requires two scopes on the API key:

crm — the shared scope for the whole section, required by all /v1/items/* and /v1/userfields/*.
userfieldconfig — a separate scope for managing smart process fields. Optional — select it in the access scopes list when creating the key.

Without the userfieldconfig scope, any request (except /types, for which crm is enough) returns 403 BITRIX_ACCESS_DENIED. The scope is fixed when the key is issued: if you add the permission to an existing key, you must reissue it — otherwise the scope is not applied. The /types endpoint uses only crm.

Field name mapping

The request body and the response use camelCase names. Nested structures (settings, elements of the enum array) are returned by Bitrix24 "as is" — the table helps you read them.

API (camelCase)	Bitrix24 (UPPER_CASE)
API (camelCase)`id`	Bitrix24 (UPPER_CASE)`ID`
API (camelCase)`entityId`	Bitrix24 (UPPER_CASE)`ENTITY_ID`
API (camelCase)`fieldName`	Bitrix24 (UPPER_CASE)`FIELD_NAME`
API (camelCase)`userTypeId`	Bitrix24 (UPPER_CASE)`USER_TYPE_ID`
API (camelCase)`xmlId`	Bitrix24 (UPPER_CASE)`XML_ID`
API (camelCase)`sort`	Bitrix24 (UPPER_CASE)`SORT`
API (camelCase)`multiple`	Bitrix24 (UPPER_CASE)`MULTIPLE`
API (camelCase)`mandatory`	Bitrix24 (UPPER_CASE)`MANDATORY`
API (camelCase)`showFilter`	Bitrix24 (UPPER_CASE)`SHOW_FILTER`
API (camelCase)`showInList`	Bitrix24 (UPPER_CASE)`SHOW_IN_LIST`
API (camelCase)`editInList`	Bitrix24 (UPPER_CASE)`EDIT_IN_LIST`
API (camelCase)`isSearchable`	Bitrix24 (UPPER_CASE)`IS_SEARCHABLE`
API (camelCase)`label`	Bitrix24 (UPPER_CASE)`LABEL`
API (camelCase)`editFormLabel`	Bitrix24 (UPPER_CASE)`EDIT_FORM_LABEL`
API (camelCase)`listColumnLabel`	Bitrix24 (UPPER_CASE)`LIST_COLUMN_LABEL`
API (camelCase)`listFilterLabel`	Bitrix24 (UPPER_CASE)`LIST_FILTER_LABEL`
API (camelCase)`errorMessage`	Bitrix24 (UPPER_CASE)`ERROR_MESSAGE`
API (camelCase)`helpMessage`	Bitrix24 (UPPER_CASE)`HELP_MESSAGE`
API (camelCase)`settings`	Bitrix24 (UPPER_CASE)`SETTINGS`
API (camelCase)`enum`	Bitrix24 (UPPER_CASE)options of an `enumeration`-type field (see Get field)

On create or update, label fills each of the three labels unless that label is explicitly provided: the edit form label (editFormLabel), the list column header (listColumnLabel) and the filter label (listFilterLabel). Explicit labels are preserved independently. A string label is converted to { "ru": "value" }. Use an object keyed by language code for other languages.

Typical scenario

Get the list of smart processes in the Bitrix24 account: GET /v1/smart-processes.
Pick the entityTypeId of the desired type from the response.
View the smart process's existing fields: GET /v1/items/:entityTypeId/userfields.
Create a new field: POST /v1/items/:entityTypeId/userfields.
Update (PATCH) or delete (DELETE) by the id of an individual field record.