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 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
`deals`	`CRM_DEAL`	Deal
`leads`	`CRM_LEAD`	Lead
`contacts`	`CRM_CONTACT`	Contact
`companies`	`CRM_COMPANY`	Company
`quotes`	`CRM_QUOTE`	Quote
`requisites`	`CRM_REQUISITE`	Requisites

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)
`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`
`list`	`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.

Previously, some of these flags could not be enabled with a boolean: the request succeeded, but the flag stayed off. That no longer happens.

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. The letters "I" and "S" that the create and update pages used to recommend are not accepted by crm.<entity>.userfield.* — they 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. Details — Value format by type.
Update (PATCH) or delete (DELETE) by identifier.