Обновить пользовательское поле user.userfield.update

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

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

Scope: user.userfield

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

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

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

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

Название
тип

Описание

id*
integer

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

Для получения идентификаторов пользовательских полей используйте метод user.userfield.list

fields
object

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

Параметр fields

Название
тип

Описание

XML_ID
string

Внешний код

SORT
integer

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

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
        
        bitrix_id = 176
        fields = {
            "XML_ID": "UF_USR_SKILLS_PROFILE_V2",
            "SORT": 200,
            "MANDATORY": "N",
            "SHOW_FILTER": "Y",
            "SHOW_IN_LIST": "Y",
            "EDIT_IN_LIST": "Y",
            "IS_SEARCHABLE": "Y",
            "SETTINGS": {
                "DEFAULT_VALUE": "Senior Python integration engineer",
                "ROWS": 4,
            },
            "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": "Update the short integration skills summary.",
            },
            "LABEL": "Skills profile",
        }
        
        try:
            bitrix_response = client.user.userfield.update(
                bitrix_id=bitrix_id,
                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")
        

Примеры кода

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

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{
            "id": 42,
            "fields": {
                "SORT": 150,
                "LIST_FILTER_LABEL": "New Title",
                "LIST_COLUMN_LABEL": "New List Title"
            }
        }' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/user.userfield.update
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{
            "id": 42,
            "fields": {
                "SORT": 150,
                "LIST_FILTER_LABEL": "New Title",
                "LIST_COLUMN_LABEL": "New List Title"
            },
            "auth": "**put_access_token_here**"
        }' \
        https://**put_your_bitrix24_address**/rest/user.userfield.update
        
// 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 UpdateUserFieldResult = boolean
        
        try {
          const response = await $b24.actions.v2.call.make<UpdateUserFieldResult>({
            method: 'user.userfield.update',
            params: {
              id: 42,
              fields: {
                SORT: 150,
                LIST_FILTER_LABEL: 'New Title',
                LIST_COLUMN_LABEL: 'New List Title',
              },
            },
            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('User field updated:', 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 updateUserField() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'user.userfield.update',
                params: {
                  id: 42,
                  fields: {
                    SORT: 150,
                    LIST_FILTER_LABEL: 'New Title',
                    LIST_COLUMN_LABEL: 'New List Title',
                  },
                },
                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('User field updated:', result)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', updateUserField)
        </script>
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'user.userfield.update',
                    [
                        'id' => 42,
                        'fields' => [
                            'SORT' => 150,
                            'LIST_FILTER_LABEL' => 'New Title',
                            'LIST_COLUMN_LABEL' => 'New List Title',
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            processData($result);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error updating user field: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'user.userfield.update', 
            {
                id: 42,
                fields: {
                    SORT: 150,
                    LIST_FILTER_LABEL: 'New Title',
                    LIST_COLUMN_LABEL: 'New List Title',
                },
            },
            function(result) {
                if(result.error())
                    console.error(result.error());
                else
                    console.log(result.data());
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'user.userfield.update',
            [
                'id' => 42,
                'fields' => [
                    'SORT' => 150,
                    'LIST_FILTER_LABEL' => 'New Title',
                    'LIST_COLUMN_LABEL' => 'New List Title',
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        

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

HTTP-статус: 200

{
            "result": true,
            "time": {
                "start":1747311864.008399,
                "finish":1747311865.063292,
                "duration":1.0548930168151855,
                "processing":0.17107510566711426,
                "date_start":"2025-05-15T14:24:24+02:00",
                "date_finish":"2025-05-15T14:24:25+02:00",
                "operating":0
            }
        }
        

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

Название
тип

Описание

result
boolean

Cодержит true в случае успешного обновления пользовательского поля

time
time

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

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

HTTP-статус: 400

{
            "error":"",
            "error_description":"Access denied."
        }
        

Название
тип

Описание

error
string

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

error_description
error_description

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

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

Код

Описание

Значение

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

Access denied.

Поле с таким id не существует или доступ запрещен

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

ID is not defined or invalid

Не задан или введен неверный 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

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

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