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 — POST /v1/userfields/:entity/enum-values
• List enumeration field values — GET /v1/userfields/:entity/enum-values
• Get an enumeration field value — GET /v1/userfields/:entity/enum-values/:id
• Update a value — PATCH /v1/userfields/:entity/enum-values/:id
• Delete a value — 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
Fieldid	DescriptionOption ID from the value list, not a field ID
FieldfieldId	DescriptionNumeric ID or system name from CRM custom fields or Smart Process Automation fields
Fieldvalue	DescriptionOption name
FieldisDefault	DescriptionWhether the option is selected by default
Fieldsort	DescriptionDisplay order
FieldxmlId	DescriptionExternal 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.
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.
2. Read its options, passing the field ID.
3. Add an option, then update or delete it by ID.

Limits

Limit	Value
LimitList page	Valuelimit defaults to 50, offset to 0. One request reads one page
LimitCount	ValueNo collection total is returned
LimitValue validation	ValueBitrix24 checks restrictions and permissions

See also

• CRM dictionaries and stage settings
• User fields
• Keys and authorization