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

Scope: user.userfield

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

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

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

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

Название
тип

Описание

fields*
object

Значения полей для добавления нового пользовательского поля

Параметр fields

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

Название
тип

Описание

FIELD_NAME*
string

Название (код) поля. Дополняется префиксом UF_USR_

USER_TYPE_ID*
string

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

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

XML_ID
string

Внешний код

SORT
integer

Порядок сортировки

MULTIPLE
boolean

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

  • Y — да
  • N — нет

MANDATORY
boolean

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

  • Y — да
  • N — нет

SHOW_FILTER
boolean

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

  • Y — да
  • N — нет

SHOW_IN_LIST
boolean

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

  • Y — да
  • N — нет

EDIT_IN_LIST
boolean

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

  • Y — да
  • N — нет

IS_SEARCHABLE
boolean

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

  • Y — да
  • N — нет

SETTINGS
object

Объект в формате {"field_1": "value_1", ... "field_N": "value_N"} для передачи дополнительных настроек пользовательских полей. Настройки описаны ниже

EDIT_FORM_LABEL
string

Подпись в форме редактирования. Можно передать строку или объект с подписями по языкам в формате {"ru": "...", "en": "..."}. При передаче строки значение будет выставлено для всех языков

LIST_COLUMN_LABEL
string

Заголовок столбца в списке. Можно передать строку или объект с подписями по языкам в формате {"ru": "...", "en": "..."}. При передаче строки значение будет выставлено для всех языков

LIST_FILTER_LABEL
string

Заголовок фильтра в списке. Можно передать строку или объект с подписями по языкам в формате {"ru": "...", "en": "..."}. При передаче строки значение будет выставлено для всех языков

ERROR_MESSAGE
string

Сообщение об ошибке при невалидном вводе. Можно передать строку или объект с текстами по языкам в формате {"ru": "...", "en": "..."}. При передаче строки значение будет выставлено для всех языков

HELP_MESSAGE
string

Текст подсказки к полю. Можно передать строку или объект с текстами по языкам в формате {"ru": "...", "en": "..."}. При передаче строки значение будет выставлено для всех языков

LABEL
string

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

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

Параметр 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

Если необходимо через API создать пользовательское поле с добавленным пользовательским типом, в поле USER_TYPE_ID необходимо указывать rest_<номер приложения>_<USER_TYPE_ID добавленного типа>. Например rest_436278_test_type.

Примеры кода

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

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields": {
                "FIELD_NAME": "UF_USER_DEALS",
                "USER_TYPE_ID": "crm",
                "XML_ID": "UF_CRM_DEALS",
                "SORT": 100,
                "MULTIPLE": "Y",
                "MANDATORY": "N",
                "SHOW_FILTER": "N",
                "SHOW_IN_LIST": "Y",
                "EDIT_IN_LIST": "Y",
                "SETTINGS": {
                    "DEAL": "Y"
                },
                "LABEL": "Привязка к сделкам CRM",
                "EDIT_FORM_LABEL": {
                    "ru": "Привязка к сделкам CRM"
                }
            }
        }' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/user.userfield.add
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields": {
                "FIELD_NAME": "UF_USER_DEALS",
                "USER_TYPE_ID": "crm",
                "XML_ID": "UF_CRM_DEALS",
                "SORT": 100,
                "MULTIPLE": "Y",
                "MANDATORY": "N",
                "SHOW_FILTER": "N",
                "SHOW_IN_LIST": "Y",
                "EDIT_IN_LIST": "Y",
                "SETTINGS": {
                    "DEAL": "Y"
                },
                "LABEL": "Привязка к сделкам CRM",
                "EDIT_FORM_LABEL": {
                    "ru": "Привязка к сделкам CRM"
                }
            },
            "auth": "**put_access_token_here**"
        }' \
        https://**put_your_bitrix24_address**/rest/user.userfield.add
        
try
        {
            const response = await $b24.callMethod(
                'user.userfield.add',
                {
                    fields: {
                        FIELD_NAME: 'UF_USER_DEALS',
                        USER_TYPE_ID: 'crm',
                        XML_ID: 'UF_CRM_DEALS',
                        SORT: 100,
                        MULTIPLE: 'Y',
                        MANDATORY: 'N',
                        SHOW_FILTER: 'N',
                        SHOW_IN_LIST: 'Y',
                        EDIT_IN_LIST: 'Y',
                        SETTINGS: {
                            DEAL: 'Y',
                        },
                        LABEL: 'Привязка к сделкам CRM',
                        EDIT_FORM_LABEL: {
                            ru: 'Привязка к сделкам CRM'
                        },
                    }
                }
            );
        
            const result = response.getData().result;
            console.log('Created element with ID:', result);
            processResult(result);
        }
        catch( error )
        {
            console.error('Error:', error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'user.userfield.add',
                    [
                        'fields' => [
                            'FIELD_NAME' => 'UF_USER_DEALS',
                            'USER_TYPE_ID' => 'crm',
                            'XML_ID' => 'UF_CRM_DEALS',
                            'SORT' => 100,
                            'MULTIPLE' => 'Y',
                            'MANDATORY' => 'N',
                            'SHOW_FILTER' => 'N',
                            'SHOW_IN_LIST' => 'Y',
                            'EDIT_IN_LIST' => 'Y',
                            'SETTINGS' => [
                                'DEAL' => 'Y',
                            ],
                            'LABEL' => 'Привязка к сделкам CRM',
                            'EDIT_FORM_LABEL' => [
                                'ru' => 'Привязка к сделкам CRM'
                            ],
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            processData($result);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error adding user field: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'user.userfield.add', 
            {
                fields: {
                    FIELD_NAME: "UF_USER_DEALS",
                    USER_TYPE_ID: "crm",
                    XML_ID: "UF_CRM_DEALS",
                    SORT: 100,
                    MULTIPLE: "Y",
                    MANDATORY: "N",
                    SHOW_FILTER: "N",
                    SHOW_IN_LIST: "Y",
                    EDIT_IN_LIST: "Y",
                    SETTINGS: {
                        DEAL: "Y",
                    },
                    LABEL: "Привязка к сделкам CRM",
                    EDIT_FORM_LABEL: {
                        ru: "Привязка к сделкам CRM"
                    },
                },
            },
            function(result)
            {
                if(result.error())
                    console.error(result.error());
                else
                    console.log(result.data());
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'user.userfield.add',
            [
                'fields' => [
                    'FIELD_NAME' => 'UF_USER_DEALS',
                    'USER_TYPE_ID' => 'crm',
                    'XML_ID' => 'UF_CRM_DEALS',
                    'SORT' => 100,
                    'MULTIPLE' => 'Y',
                    'MANDATORY' => 'N',
                    'SHOW_FILTER' => 'N',
                    'SHOW_IN_LIST' => 'Y',
                    'EDIT_IN_LIST' => 'Y',
                    'SETTINGS' => [
                        'DEAL' => 'Y',
                    ],
                    'LABEL' => 'Привязка к сделкам CRM',
                    'EDIT_FORM_LABEL' => [
                        'ru' => 'Привязка к сделкам CRM'
                    ],
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

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

HTTP-статус: 200

{
            "result":177,
            "time":{
                "start":1747301035.550121,
                "finish":1747301037.514112,
                "duration":1.9639909267425537,
                "processing":0.5865437984466553,
                "date_start":"2025-05-15T11:23:55+02:00",
                "date_finish":"2025-05-15T11:23:57+02:00",
                "operating":0
            }
        }

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

Название
тип

Описание

result
integer

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

time
time

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

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

HTTP-статус: 400

{
           "error":"",
           "error_description":"The \u0027FIELD_NAME\u0027 field is not found."
        }

Название
тип

Описание

error
string

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

error_description
error_description

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

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

Код

Описание

Значение

ERROR_ARGUMENT

Argument 'USER_TYPE_ID' is null or empty

Не задан USER_TYPE_ID

ERROR_ARGUMENT

Argument 'HANDLER' is null or empty

Не задан HANDLER

ERROR_CORE

Поле *** для объекта USER уже существует

Поле *** для объекта USER уже существует

ERROR_CORE

Fail to create new user field

Ошибка при создании поля

Пустая строка

The \u0027FIELD_NAME\u0027 field is not found.

Не задано обязательное поле FIELD_NAME

Пустая строка

The \u0027USER_TYPE_ID\u0027 field is not found.

Не задано обязательное поле USER_TYPE_ID

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

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

Превышен лимит на интенсивность запросов

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

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Предыдущая
Обзор методов
Следующая
Удалить пользовательское поле