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

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

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

Scope: user.userfield

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

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

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

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

Название
тип

Описание

fields*
object

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

Параметр fields

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

Название
тип

Описание

FIELD_NAME*
string

Название (код) поля. Битрикс24 приводит его к верхнему регистру и дополняет префиксом UF_USR_:

  • DEALS и UF_DEALS превратятся в UF_USR_DEALS
  • UF_USR_DEALS останется без изменений

Итоговый код поля возвращает метод user.userfield.list

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_USR_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_USR_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_USR_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_USR_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_USR_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_USR_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_USR_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>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "user.userfield.add", b24.Params{
	"fields": b24.Params{
		"FIELD_NAME":   "UF_USR_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": b24.Params{
			"DEAL": "Y",
		},
		"LABEL": "Привязка к сделкам CRM",
		"EDIT_FORM_LABEL": b24.Params{
			"ru": "Привязка к сделкам CRM",
		},
	},
})
if err != nil {
	return fmt.Errorf("user.userfield.add: %w", err)
}

var newID b24.ID
if err := json.Unmarshal(res.Result, &newID); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println("идентификатор:", newID)

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

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

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

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