CRM entity fields

Create, read, update, and delete user fields for the fixed CRM entities: deals, leads, contacts, companies, quotes, and requisites. The entity is set in the request path (:entity).

Bitrix24 API: crm.<entity>.userfield.* Scope: crm

Operations

List entity fields — GET /v1/userfields/:entity
Type catalog — GET /v1/userfields/:entity/types
Get field — GET /v1/userfields/:entity/:id
Create field — POST /v1/userfields/:entity
Update field — PATCH /v1/userfields/:entity/:id
Delete field — DELETE /v1/userfields/:entity/:id

Supported entities

:entity in the path is one of the values below. In the response, the entityId field holds the corresponding internal Bitrix24 identifier.

`:entity`	`entityId` in response	Entity
:entity`deals`	entityId in response`CRM_DEAL`	EntityDeal
:entity`leads`	entityId in response`CRM_LEAD`	EntityLead
:entity`contacts`	entityId in response`CRM_CONTACT`	EntityContact
:entity`companies`	entityId in response`CRM_COMPANY`	EntityCompany
:entity`quotes`	entityId in response`CRM_QUOTE`	EntityQuote
:entity`requisites`	entityId in response`CRM_REQUISITE`	EntityRequisites

Field name mapping

The table describes the properties of the field itself: the request body and the response use camelCase names, while Bitrix24 stores them in UPPER_CASE. This helps you read the nested structures (settings, items of the list array) that Bitrix24 returns as-is. For the field name to use in requests to entity records, see Field values in records.

API (camelCase)	Bitrix24 (UPPER_CASE)
API (camelCase)`id`	Bitrix24 (UPPER_CASE)`ID`
API (camelCase)`entityId`	Bitrix24 (UPPER_CASE)`ENTITY_ID`
API (camelCase)`fieldName`	Bitrix24 (UPPER_CASE)`FIELD_NAME`
API (camelCase)`userTypeId`	Bitrix24 (UPPER_CASE)`USER_TYPE_ID`
API (camelCase)`xmlId`	Bitrix24 (UPPER_CASE)`XML_ID`
API (camelCase)`sort`	Bitrix24 (UPPER_CASE)`SORT`
API (camelCase)`multiple`	Bitrix24 (UPPER_CASE)`MULTIPLE`
API (camelCase)`mandatory`	Bitrix24 (UPPER_CASE)`MANDATORY`
API (camelCase)`showFilter`	Bitrix24 (UPPER_CASE)`SHOW_FILTER`
API (camelCase)`showInList`	Bitrix24 (UPPER_CASE)`SHOW_IN_LIST`
API (camelCase)`editInList`	Bitrix24 (UPPER_CASE)`EDIT_IN_LIST`
API (camelCase)`isSearchable`	Bitrix24 (UPPER_CASE)`IS_SEARCHABLE`
API (camelCase)`label`	Bitrix24 (UPPER_CASE)`LABEL`
API (camelCase)`editFormLabel`	Bitrix24 (UPPER_CASE)`EDIT_FORM_LABEL`
API (camelCase)`listColumnLabel`	Bitrix24 (UPPER_CASE)`LIST_COLUMN_LABEL`
API (camelCase)`listFilterLabel`	Bitrix24 (UPPER_CASE)`LIST_FILTER_LABEL`
API (camelCase)`errorMessage`	Bitrix24 (UPPER_CASE)`ERROR_MESSAGE`
API (camelCase)`helpMessage`	Bitrix24 (UPPER_CASE)`HELP_MESSAGE`
API (camelCase)`settings`	Bitrix24 (UPPER_CASE)`SETTINGS`
API (camelCase)`list`	Bitrix24 (UPPER_CASE)`LIST`

Yes/no flags

Six properties from the table — multiple, mandatory, showFilter, showInList, editInList, isSearchable — are stored by Bitrix24 as character flags, not as booleans. Send them either as booleans (true / false) or as the strings "Y" / "N"; the platform accepts both forms. Five of the six are stored as "Y" and "N"; showFilter has a storage form of its own — see below.

A separate note on showFilter. Enable it with a plain true or "Y"; on read, an enabled filter comes back as "E", which is Bitrix24's storage form. That "E" can be sent straight back — the platform reads it as "on", so a read-modify-write cycle does not switch the filter off. This holds when the value read is "N" or "E"; a field configured outside this method may carry a different value — do not send that one back; enable it with true instead. On write, the letters "I" and "S" switch the filter off.

Typical scenario

View the list of existing fields: GET /v1/userfields/deals.
Check the available types: GET /v1/userfields/deals/types.
Create a new field with the required userTypeId: POST /v1/userfields/deals.
Read its full description with the list values (for enumeration): GET /v1/userfields/deals/:id. When a deal is created or updated, such a field takes the option ID from data.list, not the VALUE label. A label sent instead of the ID is lost without an error. For details, see Value format by type.
Update (PATCH) or delete (DELETE) by identifier.