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

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

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

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

Пример

from b24pysdk.client import BaseClient
        from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        fields = {
            "FIELD_NAME": "UF_USR_SKILLS_PROFILE",
            "USER_TYPE_ID": "string",
            "XML_ID": "UF_USR_SKILLS_PROFILE",
            "SORT": 150,
            "MULTIPLE": "N",
            "MANDATORY": "N",
            "SHOW_FILTER": "Y",
            "SHOW_IN_LIST": "Y",
            "EDIT_IN_LIST": "Y",
            "IS_SEARCHABLE": "Y",
            "SETTINGS": {
                "DEFAULT_VALUE": "Python integration engineer",
                "ROWS": 3,
            },
            "EDIT_FORM_LABEL": {
                "en": "Skills profile",
            },
            "LIST_COLUMN_LABEL": {
                "en": "Skills profile",
            },
            "LIST_FILTER_LABEL": {
                "en": "Skills profile",
            },
            "ERROR_MESSAGE": {
                "en": "Skills profile is invalid",
            },
            "HELP_MESSAGE": {
                "en": "Store a short integration skills summary.",
            },
            "LABEL": "Skills profile",
        }
        
        try:
            bitrix_response = client.user.userfield.add(
                fields=fields,
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Ошибка Bitrix API",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print("Bitrix SDK error", error.message, sep="\n")
        except Exception as error:
            print("Unexpected error", error, sep="\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
        
// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of the payload returned in result (match the "response handling" section of the page)
        type AddUserFieldResult = number
        
        try {
          const response = await $b24.actions.v2.call.make<AddUserFieldResult>({
            method: 'user.userfield.add',
            params: {
              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 deals binding',
                EDIT_FORM_LABEL: {
                  ru: 'CRM deals binding',
                },
              },
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Created user field with ID:', result)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function addUserField() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'user.userfield.add',
                params: {
                  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 deals binding',
                    EDIT_FORM_LABEL: {
                      ru: 'CRM deals binding',
                    },
                  },
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Created user field with ID:', result)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', addUserField)
        </script>
        
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

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

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

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

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