Добавить пользовательское поле userfieldconfig.add

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: userfieldconfig, scope модуля из moduleId (например, crm)

Кто может выполнять метод: пользователь с правом изменения настроек объекта в модуле moduleId (для crm — право «Разрешить изменять настройки»)

Метод userfieldconfig.add добавляет новое пользовательское поле.

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

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

Название `тип`	Описание
moduleId* `string`	Идентификатор модуля, в котором создается поле
field* `object`	Объект с настройками пользовательского поля (подробное описание)

Параметр field

Название `тип`	Описание
entityId* `string`	Идентификатор объекта, для которого создается поле. Формат зависит от модуля, например `CRM_7` для смарт-процесса
fieldName* `string`	Код поля в формате `UF_{ИДЕНТИФИКАТОР_ОБЪЕКТА}_{POSTFIX}`. Код должен быть уникальным в рамках объекта. Допустимы символы `A-Z`, `0-9`, `_`. Максимальная длина кода 50 символов
userTypeId* `string`	Идентификатор типа поля. Список доступных типов возвращает метод userfieldconfig.getTypes
xmlId `string`	Внешний идентификатор поля
sort `integer`	Индекс сортировки. По умолчанию `100`
multiple `boolean`	Является ли поле множественным. Возможные значения: `Y` или `N`. По умолчанию `N`
mandatory `boolean`	Является ли поле обязательным. Возможные значения: `Y` или `N`. По умолчанию `N`
showFilter `boolean`	Показывать ли поле в фильтре. Возможные значения: `Y` или `N`. По умолчанию `N`
editInList `boolean`	Разрешать ли редактирование значения в списке. Возможные значения: `Y` или `N`
isSearchable `boolean`	Участвуют ли значения поля в поиске. Возможные значения: `Y` или `N`
settings `object`	Дополнительные настройки поля. Набор ключей зависит от `userTypeId` (подробное описание)
editFormLabel `string`\|`lang_map`	Подпись в форме редактирования. При передаче строки используется как общее значение, при передаче `lang_map` можно задать подпись по языкам
helpMessage `string`\|`lang_map`	Текст подсказки. При передаче строки используется как общее значение, при передаче `lang_map` можно задать подсказку по языкам
enum `uf_enum_element[]`	Варианты значений для поля типа `enumeration`

Метод использует фиксированный набор ключей в field (см. таблицу выше).

Некорректные и неподдерживаемые ключи в field игнорируются.

Ключи showInList, listColumnLabel, listFilterLabel, errorMessage, label не обрабатываются методом userfieldconfig.add, даже если переданы в field.

Параметр settings

У каждого типа поля существует свой набор ключей в settings.

string

integer

double

boolean

date|datetime

money

url

address

file

enumeration

iblock_section|iblock_element

crm_status

crm

employee

rest_*

Название `тип`	Описание
DEFAULT_VALUE `string`	Значение по умолчанию
ROWS `integer`	Количество строк в поле ввода, должно быть больше 0
SIZE `integer`	Ширина поля ввода
REGEXP `string`	Регулярное выражение для валидации
MIN_LENGTH `integer`	Минимальная длина строки
MAX_LENGTH `integer`	Максимальная длина строки

Название `тип`	Описание
DEFAULT_VALUE `integer`	Значение по умолчанию
SIZE `integer`	Ширина поля ввода
MIN_VALUE `integer`	Минимальное значение
MAX_VALUE `integer`	Максимальное значение

Название `тип`	Описание
DEFAULT_VALUE `double`	Значение по умолчанию
PRECISION `integer`	Точность числа, должна быть больше или равна 0
SIZE `integer`	Ширина поля ввода
MIN_VALUE `double`	Минимальное значение
MAX_VALUE `double`	Максимальное значение

Название `тип`	Описание
DEFAULT_VALUE `integer`	Значение по умолчанию, где `1` = да и `0` = нет
DISPLAY `string`	Внешний вид, возможные значения: `CHECKBOX`, `RADIO`, `DROPDOWN`
LABEL `string`	Подпись значения Да
LABEL_CHECKBOX `string`	Подпись для режима `CHECKBOX`

Название `тип`	Описание
DEFAULT_VALUE `object`	Значение по умолчанию в формате `{VALUE, TYPE}`, где `TYPE`: `NONE`, `NOW`, `FIXED`
USE_SECOND `boolean`	Использовать секунды в поле `datetime`
USE_TIMEZONE `boolean`	Использовать часовой пояс в поле `datetime`

Название `тип`	Описание
DEFAULT_VALUE `string`	Значение по умолчанию в формате `	{CURRENCY}`

Название `тип`	Описание
POPUP `boolean`	Открывать ссылку в новом окне
SIZE `integer`	Ширина поля ввода
MIN_LENGTH `integer`	Минимальная длина значения
MAX_LENGTH `integer`	Максимальная длина значения
DEFAULT_VALUE `string`	Значение по умолчанию
ROWS `integer`	Количество строк в поле ввода

Название `тип`	Описание
SHOW_MAP `boolean`	Показывать карту для адреса

Название `тип`	Описание
SIZE `integer`	Ширина поля ввода
LIST_WIDTH `integer`	Ширина превью в списке
LIST_HEIGHT `integer`	Высота превью в списке
MAX_SHOW_SIZE `integer`	Максимальный размер файла для показа
MAX_ALLOWED_SIZE `integer`	Максимально допустимый размер файла
EXTENSIONS `string[]`	Список разрешенных расширений
TARGET_BLANK `boolean`	Открывать файл в новой вкладке

Название `тип`	Описание
DISPLAY `string`	Внешний вид, возможные значения: `LIST`, `UI`, `CHECKBOX`, `DIALOG`
LIST_HEIGHT `integer`	Высота списка, должна быть больше 0
CAPTION_NO_VALUE `string`	Подпись пустого значения
SHOW_NO_VALUE `boolean`	Показывать пустое значение

Название `тип`	Описание
DISPLAY `string`	Внешний вид, возможные значения: `DIALOG`, `UI`, `LIST`, `CHECKBOX`
LIST_HEIGHT `integer`	Высота списка, должна быть больше 0
IBLOCK_ID `integer`	Идентификатор инфоблока
DEFAULT_VALUE `string`	Значение по умолчанию
ACTIVE_FILTER `boolean`	Использовать только активные элементы

Название `тип`	Описание

Название `тип`	Описание
LEAD `boolean`	Включить привязку к лидам
CONTACT `boolean`	Включить привязку к контактам
COMPANY `boolean`	Включить привязку к компаниям
DEAL `boolean`	Включить привязку к сделкам
QUOTE `boolean`	Включить привязку к предложениям
ORDER `boolean`	Включить привязку к заказам
SMART_INVOICE `boolean`	Включить привязку к счетам
DYNAMIC_* `boolean`	Включить привязку к смарт-процессу с конкретным `typeId`

Отдельные настройки в settings для типа employee не используются

Настройки определяются обработчиком пользовательского типа поля

Тип uf_enum_element

Название `тип`	Описание
value* `string`	Значение варианта списка
def `boolean`	Флаг значения по умолчанию (`Y`/`N`)
sort `integer`	Индекс сортировки варианта
xmlId `string`	Внешний идентификатор варианта

Примеры кода

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

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "moduleId": "crm",
            "field": {
              "entityId": "CRM_7",
              "fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
              "userTypeId": "enumeration",
              "multiple": "Y",
              "editFormLabel": {
                "ru": "Список характеристик",
                "en": "List of characteristics"
              },
              "enum": [
                { "value": "Характеристика 1", "def": "N", "sort": 100 },
                { "value": "Характеристика 2", "def": "Y", "sort": 200 }
              ]
            }
          }' \
          "https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/userfieldconfig.add"

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "moduleId": "crm",
            "field": {
              "entityId": "CRM_7",
              "fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
              "userTypeId": "enumeration",
              "multiple": "Y",
              "editFormLabel": {
                "ru": "Список характеристик",
                "en": "List of characteristics"
              },
              "enum": [
                { "value": "Характеристика 1", "def": "N", "sort": 100 },
                { "value": "Характеристика 2", "def": "Y", "sort": 200 }
              ]
            },
            "auth": "**put_access_token_here**"
          }' \
          "https://**put_your_bitrix24_address**/rest/userfieldconfig.add"

const endpoint = "https://**put_your_bitrix24_address**/rest/userfieldconfig.add.json";
        
        fetch(endpoint, {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
                auth: "**put_access_token_here**",
                moduleId: "crm",
                field: {
                    entityId: "CRM_7",
                    fieldName: "UF_CRM_7_NEW_REST_LIST_2026",
                    userTypeId: "enumeration",
                    multiple: "Y",
                    editFormLabel: {
                        ru: "Список характеристик",
                        en: "List of characteristics",
                    },
                    enum: [
                        { value: "Характеристика 1", def: "N", sort: 100 },
                        { value: "Характеристика 2", def: "Y", sort: 200 },
                    ],
                },
            }),
        })
            .then((response) => response.json())
            .then((data) => console.log(data))
            .catch((error) => console.error(error));

$payload = [
            'auth' => '**put_access_token_here**',
            'moduleId' => 'crm',
            'field' => [
                'entityId' => 'CRM_7',
                'fieldName' => 'UF_CRM_7_NEW_REST_LIST_2026',
                'userTypeId' => 'enumeration',
                'multiple' => 'Y',
                'editFormLabel' => [
                    'ru' => 'Список характеристик',
                    'en' => 'List of characteristics',
                ],
                'enum' => [
                    ['value' => 'Характеристика 1', 'def' => 'N', 'sort' => 100],
                    ['value' => 'Характеристика 2', 'def' => 'Y', 'sort' => 200],
                ],
            ],
        ];
        
        $curl = curl_init('https://**put_your_bitrix24_address**/rest/userfieldconfig.add.json');
        curl_setopt_array($curl, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
            CURLOPT_POSTFIELDS => json_encode($payload),
        ]);
        
        $result = curl_exec($curl);
        curl_close($curl);
        
        print_r($result);

BX24.callMethod(
            "userfieldconfig.add",
            {
                moduleId: "crm",
                field: {
                    entityId: "CRM_7",
                    fieldName: "UF_CRM_7_NEW_REST_LIST_2026",
                    userTypeId: "enumeration",
                    multiple: "Y",
                    editFormLabel: {
                        ru: "Список характеристик",
                        en: "List of characteristics",
                    },
                    enum: [
                        { value: "Характеристика 1", def: "N", sort: 100 },
                        { value: "Характеристика 2", def: "Y", sort: 200 },
                    ],
                },
            },
            (result) => {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.info(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'userfieldconfig.add',
            [
                'moduleId' => 'crm',
                'field' => [
                    'entityId' => 'CRM_7',
                    'fieldName' => 'UF_CRM_7_NEW_REST_LIST_2026',
                    'userTypeId' => 'enumeration',
                    'multiple' => 'Y',
                    'editFormLabel' => [
                        'ru' => 'Список характеристик',
                        'en' => 'List of characteristics',
                    ],
                    'enum' => [
                        ['value' => 'Характеристика 1', 'def' => 'N', 'sort' => 100],
                        ['value' => 'Характеристика 2', 'def' => 'Y', 'sort' => 200],
                    ],
                ],
            ]
        );
        
        echo '<pre>';
        print_r($result);
        echo '</pre>';

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

HTTP-статус: 200

{
            "result": {
                "field": {
                    "id": "6953",
                    "entityId": "CRM_7",
                    "fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
                    "userTypeId": "enumeration",
                    "xmlId": null,
                    "sort": "100",
                    "multiple": "Y",
                    "mandatory": "N",
                    "showFilter": "N",
                    "showInList": "Y",
                    "editInList": "Y",
                    "isSearchable": "N",
                    "settings": {
                        "DISPLAY": "LIST",
                        "LIST_HEIGHT": 1,
                        "CAPTION_NO_VALUE": "",
                        "SHOW_NO_VALUE": "Y"
                    },
                    "languageId": {
                        "en": "en",
                        "ru": "ru"
                    },
                    "editFormLabel": {
                        "en": "List of characteristics",
                        "ru": "Список характеристик"
                    },
                    "listColumnLabel": {
                        "en": null,
                        "ru": null
                    },
                    "listFilterLabel": {
                        "en": null,
                        "ru": null
                    },
                    "errorMessage": {
                        "en": null,
                        "ru": null
                    },
                    "helpMessage": {
                        "en": null,
                        "ru": null
                    },
                    "enum": [
                        {
                            "id": "3363",
                            "userFieldId": "6953",
                            "value": "Характеристика 1",
                            "def": "N",
                            "sort": "100",
                            "xmlId": "56dff18efcfe25f3bae0117a6b372567"
                        },
                        {
                            "id": "3365",
                            "userFieldId": "6953",
                            "value": "Характеристика 2",
                            "def": "Y",
                            "sort": "200",
                            "xmlId": "42e3ebcf5506a65283bf3bf510d8f05a"
                        }
                    ]
                }
            },
            "time": {
                "start": 1724239307.903115,
                "finish": 1724239308.567422,
                "duration": 0.6643068790435791,
                "processing": 0.20090818405151367,
                "date_start": "2024-08-21T13:21:47+02:00",
                "date_finish": "2024-08-21T13:21:48+02:00",
                "operating": 0
            }
        }

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

Название `тип`	Описание
result `object`	Корневой элемент ответа (подробное описание)
time `time`	Информация о времени выполнения запроса

Объект result

Название `тип`	Описание
field `object`	Настройки созданного пользовательского поля (подробное описание)

Объект field

Название `тип`	Описание
id `integer`	Идентификатор настроек поля
entityId `string`	Идентификатор объекта
fieldName `string`	Код поля
userTypeId `string`	Идентификатор типа поля
xmlId `string`	Внешний идентификатор поля
sort `integer`	Индекс сортировки
multiple `boolean`	Флаг множественного значения (`Y`/`N`)
mandatory `boolean`	Флаг обязательного поля (`Y`/`N`)
showFilter `boolean`	Флаг показа поля в фильтре
showInList `boolean`	Флаг показа поля в списке
editInList `boolean`	Флаг редактирования в списке
isSearchable `boolean`	Флаг участия в поиске
settings `object`	Дополнительные настройки поля(подробное описание). Состав ключей зависит от `userTypeId`
languageId `object`	Языки, для которых заданы подписи поля
editFormLabel `lang_map`	Подписи в форме редактирования
listColumnLabel `lang_map`	Подписи колонки в списке
listFilterLabel `lang_map`	Подписи в фильтре
errorMessage `lang_map`	Текст сообщения об ошибке
helpMessage `lang_map`	Подсказка по полю
enum `object[]`	Варианты значений. Поле возвращается только для `userTypeId = enumeration`

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

HTTP-статус: 400

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

Название `тип`	Описание
error `string`	Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания
error_description `error_description`	Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

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

Код	Описание	Значение
`-`	Access denied	Недостаточно прав для создания пользовательского поля
`-`	Вы не можете создавать пользовательские поля	Ошибка может возвращаться, если `field.fieldName` не начинается с `UF_{entityId}_`
`-`	The 'USER_TYPE_ID' field is not found	Не передан обязательный `field.userTypeId`
`-`	The 'FIELD_NAME' field is not found	Не передан обязательный `field.fieldName`
`-`	Поле ... уже существует	Переданный `field.fieldName` уже используется для этого объекта
`-`	Fail to create new user field	Ошибка создания поля на стороне сервера
`-`	Fail to save enumeration field values	Ошибка сохранения значений списка для типа `enumeration`

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус	Код Текст ошибки	Описание
`500`	`INTERNAL_SERVER_ERROR` Internal server error	Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	Превышен лимит на интенсивность запросов
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически через 10 минут
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	Текущий метод не разрешен для вызова с помощью batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	Превышена максимальная длина параметров, переданных в метод batch
`401`	`NO_AUTH_FOUND` Wrong authorization data	Неверный access-токен или код вебхука
`400`	`INVALID_REQUEST` Https required	Для вызовов методов требуется использовать протокол HTTPS
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	REST API доступен только на коммерческих планах
`403`	`INVALID_CREDENTIALS` Invalid request credentials	У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	Манифест недоступен
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более высоких привилегий, чем предоставляет токен вебхука
`401`	`expired_token` The access token provided has expired	Предоставленный access-токен доступа истек
`403`	`user_access_error` The user does not have access to the application	Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям
`500`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Обзор методов

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

Добавить пользовательское поле userfieldconfig.add

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

Параметр fieldПараметр field

Параметр settingsПараметр settings

Тип uf_enum_elementТип uf_enum_element

Примеры кодаПримеры кода

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

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

Объект resultОбъект result

Объект fieldОбъект field

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

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

Статусы и коды системных ошибокСтатусы и коды системных ошибок

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