Designing Custom Fields in Bitrix24 CRM
Designing Custom Fields in Bitrix24 CRM
Custom fields are the most common way to "break" a CRM without noticing it. Adding a field takes five minutes. But over a year, 80 fields accumulate in the system — half are never filled in, a third duplicate each other, and one critical field was created as "string" instead of "list," so analytics now show 40 different spellings of the word "Kyiv."
Technical Foundations
Custom fields in Bitrix24 CRM are created through the main module (class CUserTypeManager) and stored in two places:
-
Field definition — table
b_user_field:ENTITY_ID(e.g.,CRM_LEAD,CRM_DEAL,CRM_CONTACT,CRM_COMPANY,CRM_SMART_*),FIELD_NAME(with prefixUF_CRM_),USER_TYPE_ID(type: string, integer, double, boolean, datetime, enumeration, iblock_section, crm_status, employee, etc.). -
Field values — tables
b_uts_crm_lead,b_uts_crm_deal,b_uts_crm_contact,b_uts_crm_company— one row per entity record.
Fields of type enumeration (list) store their values separately in b_user_field_enum. This is important during data migration: you cannot simply copy a numeric value from a list field between environments — the value IDs will differ.
Field Types and When to Use Each
| Type | USER_TYPE_ID | When to use |
|---|---|---|
| String | string |
Arbitrary text: name, comment |
| Integer | integer |
Quantity, ID, number |
| Decimal | double |
Amount, percentage, weight |
| List | enumeration |
Fixed set of values — statuses, types, categories |
| Date | date |
Date without time |
| Date+time | datetime |
Date with time |
| Flag (Yes/No) | boolean |
Binary attribute |
| File | file |
Documents, images |
| Employee reference | employee |
Responsible person, supervisor |
| CRM element reference | crm |
Link to deal, contact, company |
| Money | money |
Amounts with currency |
Choosing "string" instead of "list" is the most common mistake. If a value comes from a finite set of options — it's a list. Always.
The Field Design Process
Step 1. Inventory of existing fields. On live projects, it's not unusual to find 50–100 custom fields on a single entity. Some were created by different people at different times, some duplicate standard fields, some have never been filled in. Conduct an audit: which fields are used, by whom, and for what purpose.
Step 2. Identifying needs. For each team that uses the CRM, document: what they want to see in the card and what they want to get in reports. Reports are the key guide: if the data can't be aggregated, the field has the wrong type.
Step 3. Normalizing list values. For list-type fields, design the final set of values. Rule: there should be enough values to classify, but not so many that a manager can't choose within 3 seconds. 5–12 values is a workable range. If more are needed — consider a two-level list or a reference table implemented as a smart process.
Step 4. Field naming. The system name (FIELD_NAME) should be meaningful: UF_CRM_DEAL_REASON_LOSS instead of UF_CRM_1234567. This is critical for REST API integrations and during diagnostics.
Step 5. Display order and mandatory status. For each field, document: mandatory or not, on which stages mandatory, in which card block it is displayed.
Anti-patterns
A "Comment" field instead of structured data. "Reason for loss" as a text field is a journal, not analytics. After 6 months, it will contain 200 unique phrases.
A "Status" field that duplicates the standard CRM status. A custom "Internal Status" field is often just an attempt to work around funnel stages. If the stages don't work, redesigning the funnel is the right approach.
Fields for data that can be calculated. If "Amount with VAT" always equals "Amount" × 1.2 — this doesn't need to be stored; it needs to be calculated in the report.
Excessive granularity. A "Reason for choosing our company" field with 35 options — managers will pick "Other." Better to have 6 categories with an open comment field next to it.
Case Study: Field Audit and Rebuild for a Manufacturing Company
Client — a metal structure factory. 47 custom fields in the deal, created over 3 years. Task: clean up before ERP integration.
The audit revealed:
- 11 string-type fields with content that is actually enumerable (metal type, strength class, delivery region)
- 7 fields that were never filled in (all values NULL)
- 4 fields that duplicate each other ("Order Volume" and "Tonnage" — the same thing with different words)
- 2 fields with wrong type: a date written as a string in "DD.MM.YY" format
Result of the rebuild: 47 → 28 fields. String fields with enumerations were converted to enumeration, data migrated via API. Duplicate fields were merged. Unused fields were deleted after exporting data to an archive.
After normalization, the ERP integration took half as long — clean field mapping instead of parsing arbitrary text.
Timeline
Audit and design of custom fields for a single entity takes 2–4 days. For all CRM entities (lead, deal, contact, company) — 8–14 days, including data migration to new types and client approval.