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

If you pass label without explicit editFormLabel / listColumnLabel when creating or updating, the value is copied into both labels — the edit form (editFormLabel) and the list column header (listColumnLabel).

Typical scenario

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

See also

• CRM entity fields
• Employee fields
• Smart processes
• User fields