# 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](/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`

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`](/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 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](/docs/userfields/smart-processes/create). 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)](/docs/entity-api#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](/docs/userfields/smart-processes/get)) |

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

1. Get the list of smart processes in the Bitrix24 account: [`GET /v1/smart-processes`](/docs/entities/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`](/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)
- [Employee fields](/docs/userfields/users)
- [Smart processes](/docs/entities/smart-processes)
- [User fields](/docs/userfields)