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

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

У каждого типа пользовательских полей существует свой набор дополнительных настроек.

string

integer

double

boolean

datetime

enumeration

iblock_section|iblock_element

crm_status

crm

Название
тип

Описание

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`

Примеры кода

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

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

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

try
        {
            const response = await $b24.callMethod(
                'user.userfield.update',
                {
                    id: 42,
                    fields: {
                        SORT: 150,
                        LIST_FILTER_LABEL: 'New Title',
                        LIST_COLUMN_LABEL: 'New List Title',
                    }
                }
            );
        
            const result = response.getData().result;
            console.log('Updated element with ID:', result);
            processResult(result);
        }
        catch( error )
        {
            console.error('Error:', error);
        }

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	Превышен лимит на интенсивность запросов
`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	Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Получить список пользовательских полей

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

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

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

Параметр fieldsПараметр fields

Параметр SETTINGSПараметр SETTINGS

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

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

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

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

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

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

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

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

Параметр fields

Параметр SETTINGS

Примеры кода

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

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

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

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

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

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