# 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](/docs/userfields/crm/list) — `GET /v1/userfields/:entity`
- [Type catalog](/docs/userfields/crm/types) — `GET /v1/userfields/:entity/types`
- [Get field](/docs/userfields/crm/get) — `GET /v1/userfields/:entity/:id`
- [Create field](/docs/userfields/crm/create) — `POST /v1/userfields/:entity`
- [Update field](/docs/userfields/crm/update) — `PATCH /v1/userfields/:entity/:id`
- [Delete field](/docs/userfields/crm/delete) — `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](/docs/userfields#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.

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

1. View the list of existing fields: [`GET /v1/userfields/deals`](/docs/userfields/crm/list).
2. Check the available types: [`GET /v1/userfields/deals/types`](/docs/userfields/crm/types).
3. Create a new field with the required `userTypeId`: [`POST /v1/userfields/deals`](/docs/userfields/crm/create).
4. Read its full description with the list values (for `enumeration`): [`GET /v1/userfields/deals/:id`](/docs/userfields/crm/get). 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](/docs/entity-api#value-format-by-type).
5. Update ([`PATCH`](/docs/userfields/crm/update)) or delete ([`DELETE`](/docs/userfields/crm/delete)) by identifier.

## See also

- [Smart process fields](/docs/userfields/smart-processes)
- [Employee fields](/docs/userfields/users)
- [Deals](/docs/entities/deals)
- [Leads](/docs/entities/leads)
- [Contacts](/docs/entities/contacts)
- [Companies](/docs/entities/companies)
- [Requisites](/docs/entities/requisites)
- [User fields](/docs/userfields)