# CRM list field values

Add, read, update and delete individual options of a custom list field without replacing the whole field.

Bitrix24 API: `crm.<E>.field.custom.enum.*`
Scope: `crm`

> **The methods are rolling out.** They require the CRM REST v3 capability introduced after `crm 26.2200.0` and activation by an administrator. The next release version has not been published yet. An unavailable method returns `422 METHOD_NOT_YET_AVAILABLE` with `error.release`.

## Operations

- [Create a value](/docs/entities/crm-field-enum/create) — `POST /v1/userfields/:entity/enum-values`
- [List enumeration field values](/docs/entities/crm-field-enum/list) — `GET /v1/userfields/:entity/enum-values`
- [Get an enumeration field value](/docs/entities/crm-field-enum/get) — `GET /v1/userfields/:entity/enum-values/:id`
- [Update a value](/docs/entities/crm-field-enum/update) — `PATCH /v1/userfields/:entity/enum-values/:id`
- [Delete a value](/docs/entities/crm-field-enum/delete) — `DELETE /v1/userfields/:entity/enum-values/:id`

For Smart Process Automation types, the same operations use `/v1/items/:entityTypeId/userfields/enum-values`; append `/:id` for one value. `:entityTypeId=31` addresses invoice fields.

## Key fields

| Field | Description |
|---|---|
| `id` | Option ID from the [value list](/docs/entities/crm-field-enum/list), not a field ID |
| `fieldId` | Numeric ID or system name from [CRM custom fields](/docs/userfields/crm/list) or [Smart Process Automation fields](/docs/userfields/smart-processes/list) |
| `value` | Option name |
| `isDefault` | Whether the option is selected by default |
| `sort` | Display order |
| `xmlId` | External option identifier |

## Before you start

1. `:entity` accepts `deals`, `leads`, `contacts`, `companies`, `quotes`, `invoices`. For a Smart Process Automation type, use its `entityTypeId` from the [type list](/docs/entities/smart-processes/list).
2. Listing and creation require `fieldId`. Get, update and delete address an option by its own ID within the CRM type.
3. `READONLY` keys may read. Changes require `READWRITE` and the employee's Bitrix24 permissions.
4. `xmlId: null` leaves the stored external identifier unchanged. It does not clear it.

## Typical workflow

1. Find a list field in the [field list](/docs/userfields/crm/list).
2. [Read its options](/docs/entities/crm-field-enum/list), passing the field ID.
3. [Add an option](/docs/entities/crm-field-enum/create), then [update](/docs/entities/crm-field-enum/update) or [delete](/docs/entities/crm-field-enum/delete) it by ID.

## Limits

| Limit | Value |
|---|---|
| List page | `limit` defaults to 50, `offset` to 0. One request reads one page |
| Count | No collection total is returned |
| Value validation | Bitrix24 checks restrictions and permissions |

## See also

- [CRM dictionaries and stage settings](/docs/entities/crm-v3-dictionaries)
- [User fields](/docs/userfields)
- [Keys and authorization](/docs/keys-auth)