Custom Lead Fields: Overview of Methods

Custom fields store information about a lead in various data formats: string, number, link, address, and others.

Quick navigation: all methods and events

User documentation: Custom fields in CRM

How to Create a Custom FieldHow to Create a Custom Field

1. Select the field type. The list of available types is returned by the crm.userfield.types method.
2. Review which settings the selected type supports with the crm.userfield.settings.fields method.
3. Create the field with the crm.lead.userfield.add method. The required parameters are FIELD_NAME and USER_TYPE_ID.
4. Check the result with the crm.lead.userfield.list method. The full name of the created field starts with the UF_CRM_ prefix.
5. Fill in the field in leads with the crm.lead.add and crm.lead.update methods, passing its full name.

Types of Custom FieldsTypes of Custom Fields

The crm.userfield.types method returns the available field types. Pass the ID value to the USER_TYPE_ID parameter when creating a field.

[
            {
                "ID": "string",
                "title": "String"
            },
            {
                "ID": "double",
                "title": "Number"
            }
        ]
        

The crm.userfield.fields method returns the list of characteristics of the custom field itself — those that describe the field rather than the value stored in it.

{
            "FIELD_NAME": {
                "type": "string",
                "title": "Code",
                "isImmutable": true
            },
            "MANDATORY": {
                "type": "char",
                "title": "Required"
            }
        }
        

Custom Field SettingsCustom Field Settings

The set of settings depends on the field type. The crm.userfield.settings.fields method returns the settings supported by the requested type. For example, for the double type:

{
            "DEFAULT_VALUE": {
                "type": "double",
                "title": "Default value"
            },
            "PRECISION": {
                "type": "int",
                "title": "Precision"
            }
        }
        

Pass the retrieved keys in the SETTINGS object of the crm.lead.userfield.add and crm.lead.userfield.update methods.

Permissions for Working with FieldsPermissions for Working with Fields

Only a user with the "Allow to modify settings" permission in CRM can create, modify, and delete custom fields. This is a single role permission for the entire CRM module — it cannot be granted for leads separately.

Any user with read access to leads can read fields with the crm.lead.userfield.get and crm.lead.userfield.list methods.

Errors When Working with Custom FieldsErrors When Working with Custom Fields

When creating or deleting custom fields, the request may be interrupted with an error INTERNAL_SERVER_ERROR. This is an internal server error. The cause of the error can be found in the server logs at the time of the request:

• In cloud Bitrix24, submit a request to technical support to get details about the error.
• In on-premise Bitrix24, request the server error log from the server administrator or hosting administrator. Then, contact technical support and attach the log for analysis.

Common Causes of Server ErrorsCommon Causes of Server Errors

1. Up to 1016 custom fields can be created for leads—this is a limitation of the database architecture. If there are already 1016 fields for leads in Bitrix24, attempting to create a new field will result in the method crm.lead.userfield.add returning an error INTERNAL_SERVER_ERROR.

   You can check the number of custom fields for leads using the method crm.lead.userfield.list.

2. There is a limitation on servers for the execution time of a single request—max_execution_time. The standard time is 60 seconds. If the request takes longer, it will be interrupted with an error INTERNAL_SERVER_ERROR.

   The time for creating or deleting a custom field for leads depends on the number of leads. When a field is created, it is added to all lead detail forms. When a field is deleted, it is removed from all detail forms. The fewer leads in your Bitrix24, the faster fields are created and deleted.

   To check the number of leads in Bitrix24, use the method crm.lead.list.

Overview of Methods and EventsOverview of Methods and Events

Scope: crm

Who can perform the method: depending on the method