Создать пользовательское поле для лидов crm.lead.userfield.add

Scope: crm

Кто может выполнять метод: администратор CRM

Метод crm.lead.userfield.add создает новое пользовательское поле для лидов.

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

fields*
object

Объект формата:

{
            field_1: value_1,
            field_2: value_2,
            ...,
            field_n: value_n,
        }
        
  • field_n — название поля
  • value_n — значение поля

Список доступных полей описан ниже.

Некорректное поле в fields будет проигнорировано

Параметр fields

Обязательные параметры отмечены *

Название
тип

Описание

USER_TYPE_ID*
string

Тип данных пользовательского поля. Возможные значения:

  • string — строка
  • integer — целое число
  • double — число
  • boolean — да/нет
  • datetime — дата/время
  • date — дата
  • money — деньги
  • url — ссылка
  • address — адрес
  • enumeration — список
  • file — файл
  • employee — привязка к сотруднику
  • crm_status — привязка к справочнику CRM
  • iblock_section — привязка к разделам инф. блоков
  • iblock_element — привязка к элементам инф. блоков
  • crm — привязка к элементам CRM
  • пользовательские типы полей

FIELD_NAME*
string

Код поля. Уникальное.

Системное ограничение на код поля составляет 20 знаков. К названию пользовательского поля всегда добавляется префикс UF_CRM_, то есть реальная длина названия 13 знаков.

Допустимые символы: A-Z, 0-9 и _

LABEL
string

Название пользовательского поля по умолчанию.

Переданное значение будет выставлено в следующие поля: LIST_FILTER_LABEL, LIST_COLUMN_LABEL, EDIT_FORM_LABEL, ERROR_MESSAGE, HELP_MESSAGE, если в них не передано значение

XML_ID
string

Внешний код

LIST_FILTER_LABEL
string|lang_map

Подпись фильтра в списке.

При передаче строки она будет проставлена для всех идентификаторов языка.

При передаче значения типа lang_map для всех непереданных языков будет проставлено значение из LABEL.

По умолчанию значение, переданное в LABEL, проставляется для всех идентификаторов языка

LIST_COLUMN_LABEL
string|lang_map

Заголовок в списке.

При передаче строки она будет проставлена для всех идентификаторов языка.

При передаче значения типа lang_map для всех непереданных языков будет проставлено значение из LABEL.

По умолчанию значение, переданное в LABEL, проставляется для всех идентификаторов языка

EDIT_FORM_LABEL
string|lang_map

Подпись в форме редактирования.

При передаче строки она будет проставлена для всех идентификаторов языка.

При передаче значения типа lang_map для всех непереданных языков будет проставлено значение из LABEL.

По умолчанию значение, переданное в LABEL, проставляется для всех идентификаторов языка

ERROR_MESSAGE
string|lang_map

Сообщение об ошибке

HELP_MESSAGE
string|lang_map

Помощь

MULTIPLE
boolean

Является ли поле множественным. Возможные значения:

  • Y — да
  • N — нет

Поля типа boolean не могут быть множественными.

По умолчанию N

MANDATORY
boolean

Является ли поле обязательным. Возможные значения:

  • Y — да
  • N — нет

По умолчанию N

SHOW_FILTER
boolean

Показывать ли поле в фильтре. Возможные значения:

  • Y — да
  • N — нет

По умолчанию N

SETTINGS
object

Дополнительные параметры поля. Для каждого типа поля USER_TYPE_ID существует свой пул доступных настроек, описание ниже

LIST
uf_enum_element[]

Список возможных значений для пользовательского поля типа enumeration, описание ниже

По умолчанию []

SORT
integer

Индекс сортировки. Обязательно больше нуля.

По умолчанию 100

SHOW_IN_LIST
boolean

Показывать ли пользовательское поле в списке.

Данный параметр ни на что не влияет в рамках crm.

Возможные значения:

  • Y — да
  • N — нет

По умолчанию N

EDIT_IN_LIST
boolean

Разрешать ли редактирование пользователем. Возможные значения:

  • Y — да
  • N — нет

По умолчанию Y. Значение N поддерживают не все типы полей в рамках crm

IS_SEARCHABLE
boolean

Участвуют ли значения поля в поиске.

Данный параметр ни на что не влияет в рамках crm.

Возможные значения:

  • Y — да
  • N — нет

По умолчанию N

Параметр SETTINGS

У каждого типа пользовательских полей существует свой набор дополнительных настроек. Данный метод поддерживает лишь те, что описаны ниже.

Название
тип

Описание

DEFAULT_VALUE
string

Значение по умолчанию.

По умолчанию ''

ROWS
integer

Количество строк в поле ввода. Обязательно больше 0.

По умолчанию 1

Название
тип

Описание

DEFAULT_VALUE
integer

Значение по умолчанию

Название
тип

Описание

DEFAULT_VALUE
double

Значение по умолчанию

PRECISION
integer

Точность числа. Обязательно больше или равно 0.

По умолчанию 2

Название
тип

Описание

DEFAULT_VALUE
integer

Значение по умолчанию, где 1 — да, 0 — нет.

Возможные значения:

  • >= 1 -> 1
  • <= 0 -> 0

По умолчанию 0

DISPLAY
string

Внешний вид. Возможные значения:

  • CHECKBOX — флажок
  • RADIO — радиокнопки
  • DROPDOWN — выпадающий список

По умолчанию CHECKBOX

Название
тип

Описание

DEFAULT_VALUE
object

Значение по умолчанию.
Объект формата:

{
            VALUE: datetime|date,
            TYPE: 'NONE'|'NOW'|'FIXED',
        }
        

где:

  • VALUE — значение по умолчанию типа datetime или date
  • TYPE — тип значения по умолчанию:
    • NONE — не выставлять значение по умолчанию
    • NOW — использовать текущее время/дату
    • FIXED — использовать время/дату из VALUE

Значение по умолчанию:

{
            VALUE: '',
            TYPE: 'NONE',
        }
        

Название
тип

Описание

DISPLAY
string

Внешний вид. Возможные значения:

  • LIST — список
  • UI — набираемый список
  • CHECKBOX — флажки
  • DIALOG — диалог выбора сущностей

По умолчанию LIST

LIST_HEIGHT

Высота списка. Обязательно больше 0.

Доступен только при DISPLAY = LIST или DISPLAY = UI.

По умолчанию 1

Название
тип

Описание

IBLOCK_TYPE_ID
string

Идентификатор типа инфоблока.

По умолчанию ''

IBLOCK_ID
string

Идентификатор инфоблока.

По умолчанию 0

DEFAULT_VALUE
string

Значение по умолчанию.

По умолчанию ''

DISPLAY
string

Внешний вид. Возможные значения:

  • DIALOG — диалог
  • UI — набираемый список
  • LIST — список
  • CHECKBOX — флажки

По умолчанию LIST

LIST_HEIGHT
integer

Высота списка. Обязательно больше 0.

По умолчанию 1

ACTIVE_FILTER
boolean

Показывать ли элементы с включенным флагом активности. Возможные значения:

  • Y — да
  • N — нет

По умолчанию N

Название
тип

Описание

ENTITY_TYPE
string

Идентификатор типа справочника.

Используйте crm.status.entity.types, чтобы узнать возможные значения.

По умолчанию ''

Если не передать ни одну из следующих опций, то по умолчанию будет включена привязка к лидам LEAD = Y.

Название
тип

Описание

LEAD
boolean

Включена ли привязка к Лидам. Возможные значения:

  • Y — да
  • N — нет

По умолчанию N

CONTACT
boolean

Включена ли привязка к Контактам. Возможные значения:

  • Y — да
  • N — нет

По умолчанию N

COMPANY
boolean

Включена ли привязка к Компаниям. Возможные значения:

  • Y — да
  • N — нет

По умолчанию N

DEAL
boolean

Включена ли привязка к Сделкам. Возможные значения:

  • Y — да
  • N — нет

По умолчанию N

Параметр LIST

Название
тип

Описание

VALUE
string

Значение элемента списка.

Элементы списка с пустым или отсутствующим VALUE будут проигнорированы

SORT
integer

Индекс сортировки. Обязательно больше или равно 0.

По умолчанию 0

DEF
boolean

Является ли элемент списка значением по умолчанию. Возможные значения:

  • Y — да
  • N — нет

Для множественного поля допустимо несколько DEF = Y. Для не множественного, дефолтным будет считаться первый переданный элемент списка с DEF = Y.

По умолчанию N

XML_ID
string

Внешний код значения. Обязательно уникальный в рамках элементов списка пользовательского поля

Примеры кода

Как использовать примеры в документации

Пример создания пользовательского поля типа Строка

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"LABEL":"Поле Привет, мир!","USER_TYPE_ID":"string","FIELD_NAME":"HELLO_WORLD","MULTIPLE":"Y","MANDATORY":"Y","SHOW_FILTER":"Y","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию","ROWS":3},"SORT":1000,"EDIT_IN_LIST":"Y","LIST_FILTER_LABEL":"Привет, мир! Фильтр","LIST_COLUMN_LABEL":{"en":"Hello, World! Column","ru":"Привет, мир! Колонка","de":"Hallo, Welt! Spalte"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit","ru":"Привет, мир! Редактировать","de":"Hallo, Welt! Bearbeiten"},"ERROR_MESSAGE":{"en":"Hello, World! Error","ru":"Привет, мир! Ошибка","de":"Hallo, Welt! Fehler"},"HELP_MESSAGE":{"en":"Hello, World! Help","ru":"Привет, мир! Помощь","de":"Hallo, Welt! Hilfe"}}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.lead.userfield.add
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"LABEL":"Поле Привет, мир!","USER_TYPE_ID":"string","FIELD_NAME":"HELLO_WORLD","MULTIPLE":"Y","MANDATORY":"Y","SHOW_FILTER":"Y","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию","ROWS":3},"SORT":1000,"EDIT_IN_LIST":"Y","LIST_FILTER_LABEL":"Привет, мир! Фильтр","LIST_COLUMN_LABEL":{"en":"Hello, World! Column","ru":"Привет, мир! Колонка","de":"Hallo, Welt! Spalte"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit","ru":"Привет, мир! Редактировать","de":"Hallo, Welt! Bearbeiten"},"ERROR_MESSAGE":{"en":"Hello, World! Error","ru":"Привет, мир! Ошибка","de":"Hallo, Welt! Fehler"},"HELP_MESSAGE":{"en":"Hello, World! Help","ru":"Привет, мир! Помощь","de":"Hallo, Welt! Hilfe"}},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.lead.userfield.add
        
try
        {
            const response = await $b24.callMethod(
                'crm.lead.userfield.add',
                {
                    fields: {
                        LABEL: 'Поле Привет, мир!',
                        USER_TYPE_ID: 'string',
                        FIELD_NAME: 'HELLO_WORLD',
                        MULTIPLE: 'Y',
                        MANDATORY: 'Y',
                        SHOW_FILTER: 'Y',
                        SETTINGS: {
                            DEFAULT_VALUE: 'Привет, мир! Значение по умолчанию',
                            ROWS: 3,
                        },
                        SORT: 1000,
                        EDIT_IN_LIST: 'Y',
                        LIST_FILTER_LABEL: 'Привет, мир! Фильтр',
                        LIST_COLUMN_LABEL: {
                            en: 'Hello, World! Column',
                            ru: 'Привет, мир! Колонка',
                            de: 'Hallo, Welt! Spalte',
                        },
                        EDIT_FORM_LABEL: {
                            en: 'Hello, World! Edit',
                            ru: 'Привет, мир! Редактировать',
                            de: 'Hallo, Welt! Bearbeiten',
                        },
                        ERROR_MESSAGE: {
                            en: 'Hello, World! Error',
                            ru: 'Привет, мир! Ошибка',
                            de: 'Hallo, Welt! Fehler',
                        },
                        HELP_MESSAGE: {
                            en: 'Hello, World! Help',
                            ru: 'Привет, мир! Помощь',
                            de: 'Hallo, Welt! Hilfe',
                        },
                    },
                }
            );
        
            console.info(response.getData().result);
        }
        catch (error)
        {
            console.error(error);
        }
        
try {
            $userfieldItemFields = [
                'FIELD_NAME' => 'HELLO_WORLD',
                'USER_TYPE_ID' => 'string',
                'SORT' => 1000,
                'MULTIPLE' => 'Y',
                'MANDATORY' => 'Y',
                'SHOW_FILTER' => 'Y',
                'EDIT_IN_LIST' => 'Y',
                'LIST_FILTER_LABEL' => 'Привет, мир! Фильтр',
                'LIST_COLUMN_LABEL' => [
                    'en' => 'Hello, World! Column',
                    'ru' => 'Привет, мир! Колонка',
                    'de' => 'Hallo, Welt! Spalte',
                ],
                'EDIT_FORM_LABEL' => [
                    'en' => 'Hello, World! Edit',
                    'ru' => 'Привет, мир! Редактировать',
                    'de' => 'Hallo, Welt! Bearbeiten',
                ],
                'ERROR_MESSAGE' => [
                    'en' => 'Hello, World! Error',
                    'ru' => 'Привет, мир! Ошибка',
                    'de' => 'Hallo, Welt! Fehler',
                ],
                'HELP_MESSAGE' => [
                    'en' => 'Hello, World! Help',
                    'ru' => 'Привет, мир! Помощь',
                    'de' => 'Hallo, Welt! Hilfe',
                ],
                'SETTINGS' => [
                    'DEFAULT_VALUE' => 'Привет, мир! Значение по умолчанию',
                    'ROWS' => 3,
                ],
            ];
        
            $result = $serviceBuilder
                ->getCRMScope()
                ->leadUserfield()
                ->add($userfieldItemFields);
        
            print($result->getId());
        } catch (Throwable $e) {
            print('Error: ' . $e->getMessage());
        }
        
BX24.callMethod(
            'crm.lead.userfield.add',
            {
                fields: {
                    LABEL: 'Поле Привет, мир!',
                    USER_TYPE_ID: 'string',
                    FIELD_NAME: 'HELLO_WORLD',
                    MULTIPLE: 'Y',
                    MANDATORY: 'Y',
                    SHOW_FILTER: 'Y',
                    SETTINGS: {
                        DEFAULT_VALUE: 'Привет, мир! Значение по умолчанию',
                        ROWS: 3,
                    },
                    SORT: 1000,
                    EDIT_IN_LIST: 'Y',
                },
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data());
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'crm.lead.userfield.add',
            [
                'fields' => [
                    'LABEL' => 'Поле Привет, мир!',
                    'USER_TYPE_ID' => 'string',
                    'FIELD_NAME' => 'HELLO_WORLD',
                    'MULTIPLE' => 'Y',
                    'MANDATORY' => 'Y',
                    'SHOW_FILTER' => 'Y',
                    'SETTINGS' => [
                        'DEFAULT_VALUE' => 'Привет, мир! Значение по умолчанию',
                        'ROWS' => 3,
                    ],
                    'SORT' => 1000,
                    'EDIT_IN_LIST' => 'Y',
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        

Пример создания пользовательского поля типа Список

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"LABEL":"Пользовательское поле (список)","USER_TYPE_ID":"enumeration","FIELD_NAME":"ENUMERATION_EXAMPLE","MULTIPLE":"N","MANDATORY":"N","SHOW_FILTER":"Y","LIST":[{"VALUE":"Элемент списка #1","DEF":"Y","XML_ID":"XML_ID_1","SORT":100},{"VALUE":"Элемент списка #2","XML_ID":"XML_ID_2","SORT":200},{"VALUE":"Элемент списка #3","XML_ID":"XML_ID_3","SORT":300},{"VALUE":"Элемент списка #4","XML_ID":"XML_ID_4","SORT":400}],"SETTINGS":{"DISPLAY":"UI","LIST_HEIGHT":2},"SORT":2000}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.lead.userfield.add
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"LABEL":"Пользовательское поле (список)","USER_TYPE_ID":"enumeration","FIELD_NAME":"ENUMERATION_EXAMPLE","MULTIPLE":"N","MANDATORY":"N","SHOW_FILTER":"Y","LIST":[{"VALUE":"Элемент списка #1","DEF":"Y","XML_ID":"XML_ID_1","SORT":100},{"VALUE":"Элемент списка #2","XML_ID":"XML_ID_2","SORT":200},{"VALUE":"Элемент списка #3","XML_ID":"XML_ID_3","SORT":300},{"VALUE":"Элемент списка #4","XML_ID":"XML_ID_4","SORT":400}],"SETTINGS":{"DISPLAY":"UI","LIST_HEIGHT":2},"SORT":2000},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.lead.userfield.add
        
try
        {
            const response = await $b24.callMethod(
                'crm.lead.userfield.add',
                {
                    fields: {
                        LABEL: 'Пользовательское поле (список)',
                        USER_TYPE_ID: 'enumeration',
                        FIELD_NAME: 'ENUMERATION_EXAMPLE',
                        MULTIPLE: 'N',
                        MANDATORY: 'N',
                        SHOW_FILTER: 'Y',
                        LIST: [
                            { VALUE: 'Элемент списка #1', DEF: 'Y', XML_ID: 'XML_ID_1', SORT: 100 },
                            { VALUE: 'Элемент списка #2', XML_ID: 'XML_ID_2', SORT: 200 },
                            { VALUE: 'Элемент списка #3', XML_ID: 'XML_ID_3', SORT: 300 },
                            { VALUE: 'Элемент списка #4', XML_ID: 'XML_ID_4', SORT: 400 },
                        ],
                        SETTINGS: {
                            DISPLAY: 'UI',
                            LIST_HEIGHT: 2,
                        },
                        SORT: 2000,
                    },
                }
            );
        
            console.info(response.getData().result);
        }
        catch (error)
        {
            console.error(error);
        }
        
try {
            $userfieldItemFields = [
                'LABEL' => 'Пользовательское поле (список)',
                'USER_TYPE_ID' => 'enumeration',
                'FIELD_NAME' => 'ENUMERATION_EXAMPLE',
                'MULTIPLE' => 'N',
                'MANDATORY' => 'N',
                'SHOW_FILTER' => 'Y',
                'LIST' => [
                    ['VALUE' => 'Элемент списка #1', 'DEF' => 'Y', 'XML_ID' => 'XML_ID_1', 'SORT' => 100],
                    ['VALUE' => 'Элемент списка #2', 'XML_ID' => 'XML_ID_2', 'SORT' => 200],
                    ['VALUE' => 'Элемент списка #3', 'XML_ID' => 'XML_ID_3', 'SORT' => 300],
                    ['VALUE' => 'Элемент списка #4', 'XML_ID' => 'XML_ID_4', 'SORT' => 400],
                ],
                'SETTINGS' => ['DISPLAY' => 'UI', 'LIST_HEIGHT' => 2],
                'SORT' => 2000,
            ];
        
            $result = $serviceBuilder
                ->getCRMScope()
                ->leadUserfield()
                ->add($userfieldItemFields);
        
            print($result->getId());
        } catch (Throwable $e) {
            print('Error: ' . $e->getMessage());
        }
        
BX24.callMethod(
            'crm.lead.userfield.add',
            {
                fields: {
                    LABEL: 'Пользовательское поле (список)',
                    USER_TYPE_ID: 'enumeration',
                    FIELD_NAME: 'ENUMERATION_EXAMPLE',
                    MULTIPLE: 'N',
                    MANDATORY: 'N',
                    SHOW_FILTER: 'Y',
                    LIST: [
                        { VALUE: 'Элемент списка #1', DEF: 'Y', XML_ID: 'XML_ID_1', SORT: 100 },
                        { VALUE: 'Элемент списка #2', XML_ID: 'XML_ID_2', SORT: 200 },
                        { VALUE: 'Элемент списка #3', XML_ID: 'XML_ID_3', SORT: 300 },
                        { VALUE: 'Элемент списка #4', XML_ID: 'XML_ID_4', SORT: 400 },
                    ],
                    SETTINGS: { DISPLAY: 'UI', LIST_HEIGHT: 2 },
                    SORT: 2000,
                },
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data());
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'crm.lead.userfield.add',
            [
                'fields' => [
                    'LABEL' => 'Пользовательское поле (список)',
                    'USER_TYPE_ID' => 'enumeration',
                    'FIELD_NAME' => 'ENUMERATION_EXAMPLE',
                    'MULTIPLE' => 'N',
                    'MANDATORY' => 'N',
                    'SHOW_FILTER' => 'Y',
                    'LIST' => [
                        ['VALUE' => 'Элемент списка #1', 'DEF' => 'Y', 'XML_ID' => 'XML_ID_1', 'SORT' => 100],
                        ['VALUE' => 'Элемент списка #2', 'XML_ID' => 'XML_ID_2', 'SORT' => 200],
                        ['VALUE' => 'Элемент списка #3', 'XML_ID' => 'XML_ID_3', 'SORT' => 300],
                        ['VALUE' => 'Элемент списка #4', 'XML_ID' => 'XML_ID_4', 'SORT' => 400],
                    ],
                    'SETTINGS' => [
                        'DISPLAY' => 'UI',
                        'LIST_HEIGHT' => 2,
                    ],
                    'SORT' => 2000,
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        

Обработка ответа

HTTP-статус: 200

{
            "result": 6997,
            "time": {
                "start": 1753789240.8146,
                "finish": 1753789241.058695,
                "duration": 0.2440950870513916,
                "processing": 0.19217395782470703,
                "date_start": "2025-07-29T14:40:40+03:00",
                "date_finish": "2025-07-29T14:40:41+03:00",
                "operating_reset_at": 1753789840,
                "operating": 0.19216084480285645
            }
        }
        

Возвращаемые данные

Название
тип

Описание

result
integer

Корневой элемент ответа, содержит идентификатор созданного пользовательского поля

time
time

Информация о времени выполнения запроса

Обработка ошибок

HTTP-статус: 400

{
            "error": "",
            "error_description": "The 'USER_TYPE_ID' field is not found."
        }
        

Название
тип

Описание

error
string

Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания

error_description
error_description

Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

Возможные коды ошибок

Код

Описание

Значение

400

The 'FIELD_NAME' field is not found

Либо передан пустой FIELD_NAME, либо он не передан вовсе

400

Имя поля слишком длинное (больше 50-ти символов).

Переданный FIELD_NAME содержит более 50 символов

400

Имя поля содержит недопустимые символы. Допустимыми являются: A-Z, 0-9 и _.

Переданный FIELD_NAME содержит недопустимые символы

400

The 'USER_TYPE_ID' field is not found

Либо передан пустой USER_TYPE_ID, либо он не передан вовсе

400

Указан неверный пользовательский тип

Переданный USER_TYPE_ID не существует

400

Элемент списка со значением XML_ID='XML_ID' уже существует

Переданные в элементы списка XML_ID не уникальны

Продолжите изучение