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

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

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

Scope: user.userfield

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

Метод user.userfield.update изменяет настройки и подписи пользовательского поля профиля. Код FIELD_NAME, тип USER_TYPE_ID и множественность MULTIPLE после создания изменить нельзя.

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

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

Название
тип

Описание

id*
integer

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

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

fields
object

Настройки поля, которые нужно изменить (подробное описание). Непереданные настройки и подписи сохраняют текущие значения. Если fields не передан, метод ничего не меняет и возвращает true

Параметр fields

Название
тип

Описание

XML_ID
string

Внешний код

SORT
integer

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

SHOW_FILTER
string

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

  • Y — да. Метод сохраняет значение E — фильтр по маске, его возвращает user.userfield.list
  • N — нет

SETTINGS
object

Дополнительные настройки поля. Набор зависит от типа поля (подробное описание).

Передавайте только настройки, которые нужно изменить: метод дополняет сохраненные настройки, а не заменяет их целиком

LIST
object[]

Варианты значений для поля типа enumeration (подробное описание)

EDIT_FORM_LABEL
string | object

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

LIST_COLUMN_LABEL
string | object

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

LIST_FILTER_LABEL
string | object

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

ERROR_MESSAGE
string | object

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

HELP_MESSAGE
string | object

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

LABEL
string

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

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

Метод игнорирует без ошибки параметры, которые нельзя изменить: код FIELD_NAME, тип USER_TYPE_ID, признак множественности MULTIPLE, а также MANDATORY, SHOW_IN_LIST, EDIT_IN_LIST и IS_SEARCHABLE.

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

Для поля типа date метод не меняет SETTINGS: значение по умолчанию задается только при создании методом user.userfield.add.

Название
тип

Описание

DEFAULT_VALUE
object

Значение по умолчанию.

Объект формата:

{
    "VALUE": "2026-01-15",
    "TYPE": "FIXED"
}

где:

  • VALUE — значение по умолчанию типа datetime или date
  • TYPE — тип значения по умолчанию:
    • NONE — не выставлять значение по умолчанию
    • NOW — использовать текущее время/дату
    • FIXED — использовать время/дату из VALUE. Сейчас значение FIXED сохраняется некорректно: метод возвращает дату 1970-01-01. Используйте NOW или NONE

Значение по умолчанию:

{
    "VALUE": "",
    "TYPE": "NONE"
}

Название
тип

Описание

DISPLAY
string

Внешний вид. Возможные значения:

  • LIST — список
  • UI — набираемый список
  • CHECKBOX — флажки
  • DIALOG — диалог выбора сущностей

По умолчанию LIST

LIST_HEIGHT
integer

Высота списка. Обязательно больше 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
string

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

  • Y — да
  • N — нет

По умолчанию N

Название
тип

Описание

ENTITY_TYPE
string

Идентификатор типа справочника.

Используйте crm.status.entity.types, чтобы узнать возможные значения.

По умолчанию ''

Метод меняет только переданные привязки, остальные сохраняют текущие значения.

Название
тип

Описание

LEAD
string

Включена ли привязка к Лидам. Возможные значения:

  • Y — да
  • N — нет

CONTACT
string

Включена ли привязка к Контактам. Возможные значения:

  • Y — да
  • N — нет

COMPANY
string

Включена ли привязка к Компаниям. Возможные значения:

  • Y — да
  • N — нет

DEAL
string

Включена ли привязка к Сделкам. Возможные значения:

  • Y — да
  • N — нет

Для типов file, url, address, money и employee метод не меняет SETTINGS: переданные настройки игнорируются, сохраненные настройки поля остаются прежними. Для поля типа employee значение SHOW_FILTER = Y сохраняется как I — фильтр по точному совпадению.

Параметр LIST

Варианты значений для поля типа enumeration. Передавайте только варианты, которые нужно изменить, добавить или удалить: остальные варианты сохраняются.

Название
тип

Описание

ID
integer

Идентификатор существующего варианта. Его возвращает метод user.userfield.list в массиве LIST. Без ID вариант добавляется как новый

VALUE
string

Текст варианта

SORT
integer

Порядок варианта в списке

DEF
string

Вариант по умолчанию:

  • Y — да
  • N — нет

XML_ID
string

Внешний код варианта. Если при изменении варианта не передать XML_ID, метод сгенерирует новый внешний код

DEL
string

Удалить вариант с указанным ID:

  • Y — удалить

Примеры кода

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

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>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.user.userfield.update(
        bitrix_id=42,
        fields={
            "SORT": 150,
            "LIST_FILTER_LABEL": "New Title",
            "LIST_COLUMN_LABEL": "New List Title",
        },
    ).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(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {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>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "user.userfield.update", b24.Params{
	"id": 42,
	"fields": b24.Params{
		"SORT":              150,
		"LIST_FILTER_LABEL": "New Title",
		"LIST_COLUMN_LABEL": "New List Title",
	},
})
if err != nil {
	return fmt.Errorf("user.userfield.update: %w", err)
}

var ok bool
if err := json.Unmarshal(res.Result, &ok); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println("выполнено:", ok)

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

HTTP-статус: 200

{
    "result": true,
    "time": {
        "start": 1793288729,
        "finish": 1793288730.001057,
        "duration": 1.0010569095611572,
        "processing": 1,
        "date_start": "2026-10-29T18:45:29+03:00",
        "date_finish": "2026-10-29T18:45:30+03:00",
        "operating_reset_at": 1793289300,
        "operating": 0
    }
}

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

Название
тип

Описание

result
boolean

true, если поле обновлено

time
time

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

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

HTTP-статус: 400

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

Название
тип

Описание

error
string

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

error_description
string

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

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

Статус

Код

Описание

Значение

400

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

Access denied.

У пользователя нет прав администратора, поле с переданным id не найдено или это системное поле профиля без префикса UF_USR_. Системные поля через REST менять нельзя

400

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

ID is not defined or invalid.

Не передан id или передано значение меньше 1

401

insufficient_scope

The request requires higher privileges than provided by the webhook token

У вебхука или приложения нет scope user.userfield

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

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

Код
Текст ошибки

Описание

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

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

403

FEATURE_NOT_AVAILABLE_ON_CURRENT_PLAN
Функция недоступна на текущем тарифе.

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

401

INVALID_CREDENTIALS
Invalid request credentials

Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

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

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