# 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](/docs/userfields/smart-processes/list) — `GET /v1/items/:entityTypeId/userfields`
- [Type catalog](/docs/userfields/smart-processes/types) — `GET /v1/items/:entityTypeId/userfields/types`
- [Get field](/docs/userfields/smart-processes/get) — `GET /v1/items/:entityTypeId/userfields/:id`
- [Create field](/docs/userfields/smart-processes/create) — `POST /v1/items/:entityTypeId/userfields`
- [Update field](/docs/userfields/smart-processes/update) — `PATCH /v1/items/:entityTypeId/userfields/:id`
- [Delete field](/docs/userfields/smart-processes/delete) — `DELETE /v1/items/:entityTypeId/userfields/:id`

## Getting `entityTypeId`

The smart process type identifier is returned in the response of [`GET /v1/smart-processes`](/docs/entities/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](/docs/userfields/crm) section — it works with a fixed set of entities via the `:entity` name.

In the responses of smart process userfield endpoints, the `entityId` field comes in the `CRM_<typeId>` format, where `typeId` is the internal sequential identifier of the smart process. This does not match the public `entityTypeId` from the request path. Similarly, the field code (`fieldName`) is built from the `UF_CRM_<typeId>_<suffix>` template.

## Key scope requirements

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

- `crm` — the general section scope for all `/v1/items/*` and `/v1/userfields/*`.
- `userfieldconfig` — a separate scope for managing smart process fields. Optional — check it in the permission 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 at the moment 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 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 the `enumeration` field (see [Get field](/docs/userfields/smart-processes/get)) |

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 Bitrix24 account's list of smart processes: [`GET /v1/smart-processes`](/docs/entities/smart-processes).
2. Pick the `entityTypeId` of the desired type from the response.
3. Look at the smart process's existing fields: [`GET /v1/items/:entityTypeId/userfields`](/docs/userfields/smart-processes/list).
4. Create a new field: [`POST /v1/items/:entityTypeId/userfields`](/docs/userfields/smart-processes/create).
5. Update ([`PATCH`](/docs/userfields/smart-processes/update)) or delete ([`DELETE`](/docs/userfields/smart-processes/delete)) by the `id` of an individual field record.

## See also

- [CRM entity fields](/docs/userfields/crm)
- [Smart processes](/docs/entities/smart-processes)
- [User fields](/docs/userfields)