# crm.deal.userfield.update

URL: https://chugunov.pro/api-bitrix24/crm/deals/user-defined-fields/crm-deal-userfield-update/
Проверено на Битрикс24 REST API, обновлено 11.09.2026 (ревизия источника fb39d6c).
Источник: официальная документация Битрикс24 (bitrix-tools/b24-rest-docs, лицензия MIT, © Bitrix). Справочник независимый, официальной документацией не является.

Изменить существующее пользовательское поле сделок
Scope: `crm`
Кто может выполнять метод: администратор CRM

## Описание

Метод `crm.deal.userfield.update` обновляет существующее пользовательское поле сделок.

## Параметры

- `id` `integer` — обязательный. Идентификатор пользовательского поля.
  Идентификатор можно получить с помощью методов [crm.deal.userfield.add](https://chugunov.pro/api-bitrix24/crm/deals/user-defined-fields/crm-deal-userfield-add/) и [crm.deal.userfield.list](https://chugunov.pro/api-bitrix24/crm/deals/user-defined-fields/crm-deal-userfield-list/)
- `fields` `object` — обязательный. Объект формата:
  ```
  {
      field_1: value_1,
      field_2: value_2,
      ...,
      field_n: value_n,
  }
  ```
  - `field_n` — название поля
  - `value_n` — новое значение поля
  Список доступных полей описан [ниже](#parameter-fields).
  Некорректное поле в `fields` будет проигнорировано.
  В `fields` нужно передавать только те поля, которые требуется изменить

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

- `MANDATORY` `boolean` — необязательный. Является ли поле обязательным. Возможные значения:
  - `Y` — да
  - `N` — нет
- `SHOW_FILTER` `boolean` — необязательный. Показывать ли поле в фильтре. Возможные значения:
  - `Y` — да
  - `N` — нет
- `XML_ID` `string` — необязательный. Внешний код
- `SETTINGS` `object` — необязательный. Дополнительные параметры поля. Для каждого типа поля `USER_TYPE_ID` существует свой пул доступных настроек, они описаны [ниже](#settings).
  Поле перезаписывает лишь переданные значения
- `LIST` `uf_enum_element[]` — необязательный. Список возможных значений для пользовательского поля типа `enumeration`, описание [ниже](#uf_enum_element)
- `SORT` `integer` — необязательный. Индекс сортировки. Обязательно больше нуля
- `SHOW_IN_LIST` `boolean` — необязательный. Показывать ли пользовательское поле в списке.
  Данный параметр ни на что не влияет в рамках `crm`.
  Возможные значения:
  - `Y` — да
  - `N` — нет
- `EDIT_IN_LIST` `boolean` — необязательный. Разрешать ли редактирование пользователем. Возможные значения:
  - `Y` — да
  - `N` — нет 
  Значение `N` поддерживают не все типы полей в рамках `crm`
- `IS_SEARCHABLE` `boolean` — необязательный. Участвуют ли значения поля в поиске.
  Данный параметр ни на что не влияет в рамках `crm`.
  Возможные значения:
  - `Y` — да
  - `N` — нет
- `LIST_FILTER_LABEL` `string` — необязательный. Подпись фильтра в списке.
  При передаче строки она устанавливается для каждого языка.
  Для языков, у которых явно не указано значение, будет записано `''`.
  Поле полностью перезаписывает предыдущее значение
- `LIST_COLUMN_LABEL` `string` — необязательный. Заголовок в списке.
  При передаче строки она устанавливается для каждого языка.
  Для языков, у которых явно не указано значение, будет записано `''`.
  Поле полностью перезаписывает предыдущее значение
- `EDIT_FORM_LABEL` `string` — необязательный. Подпись в форме редактирования.
  При передаче строки она устанавливается для каждого языка.
  Для языков, у которых явно не указано значение, будет записано `''`.
  Поле полностью перезаписывает предыдущее значение
- `ERROR_MESSAGE` `string` — необязательный. Сообщение об ошибке
- `HELP_MESSAGE` `string` — необязательный. Помощь

### Параметр LIST

- `VALUE` `string` — необязательный. Значение элемента списка.
  Элементы списка с пустым или отсутствующим `VALUE` будут проигнорированы
- `SORT` `integer` — необязательный. Индекс сортировки. Обязательно больше или равно 0
- `DEF` `boolean` — необязательный. Является ли элемент списка значением по умолчанию. Возможные значения:
  - `Y` — да
  - `N` — нет
  Для множественного поля допустимо несколько `DEF = Y`. Для не множественного, дефолтным будет считаться первый переданный элемент списка с `DEF = Y`
- `XML_ID` `string` — необязательный. Внешний код значения. Обязательно уникальный в рамках элементов списка пользовательского поля

## Ответ

HTTP-статус: 200

```json
{
    "result": true,
    "time": {
        "start": 1753790234.592207,
        "finish": 1753790234.762644,
        "duration": 0.17043709754943848,
        "processing": 0.11566615104675293,
        "date_start": "2025-07-29T14:57:14+03:00",
        "date_finish": "2025-07-29T14:57:14+03:00",
        "operating_reset_at": 1753790834,
        "operating": 0.11564803123474121
    }
}
```

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

- `result` `boolean`. Корневой элемент ответа, содержит `true` в случае успеха
- `time` `time`. Информация о времени выполнения запроса

## Ошибки

HTTP-статус: 400

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

- `400` — `Parameter 'fields' must be array`. Переданный `fields` не является объектом
- `400` — `ID is not defined or invalid`. Переданный `id` меньше нуля или не передан вовсе
- `403` — `Access denied`. Возникает в случаях, когда:
  - у пользователя нет административных прав
  - пользователь пытается изменить пользовательское поле, не привязанное к сделкам
- `ERROR_NOT_FOUND` — `The entity with ID 'id' is not found`. Пользовательского поля с переданным `id` не существует
- `ERROR_CORE` — `Элемент списка со значением XML_ID='XML_ID' уже существует`. Переданный `XML_ID` у элемента списка обязан быть уникальным в рамках элементов списка отдельно взятого пользовательского поля

## Примеры запроса

### cURL (Webhook)

```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"id":536,"fields":{"MANDATORY":"N","SHOW_FILTER":"N","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию (изменено)","ROWS":10},"SORT":2000,"EDIT_IN_LIST":"N","LIST_FILTER_LABEL":"Привет, мир! Фильтр (изменено)","LIST_COLUMN_LABEL":{"en":"Hello, World! Column (changed)","ru":"Привет, мир! Колонка (изменено)","de":"Hallo, Welt! Spalte (geändert)"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit (changed)","ru":"Привет, мир! Редактировать (изменено)","de":"Hallo, Welt! Bearbeiten (geändert)"},"ERROR_MESSAGE":{"en":"Hello, World! Error (changed)","ru":"Привет, мир! Ошибка (изменено)","de":"Hallo, Welt! Fehler (geändert)"},"HELP_MESSAGE":{"en":"Hello, World! Help (changed)","ru":"Привет, мир! Помощь (изменено)","de":"Hallo, Welt! Hilfe (geändert)"}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.deal.userfield.update
```

### cURL (OAuth)

```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"id":536,"fields":{"MANDATORY":"N","SHOW_FILTER":"N","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию (изменено)","ROWS":10},"SORT":2000,"EDIT_IN_LIST":"N","LIST_FILTER_LABEL":"Привет, мир! Фильтр (изменено)","LIST_COLUMN_LABEL":{"en":"Hello, World! Column (changed)","ru":"Привет, мир! Колонка (изменено)","de":"Hallo, Welt! Spalte (geändert)"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit (changed)","ru":"Привет, мир! Редактировать (изменено)","de":"Hallo, Welt! Bearbeiten (geändert)"},"ERROR_MESSAGE":{"en":"Hello, World! Error (changed)","ru":"Привет, мир! Ошибка (изменено)","de":"Hallo, Welt! Fehler (geändert)"},"HELP_MESSAGE":{"en":"Hello, World! Help (changed)","ru":"Привет, мир! Помощь (изменено)","de":"Hallo, Welt! Hilfe (geändert)"}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.deal.userfield.update
```

### BX24.js

```js
BX24.callMethod(
    'crm.deal.userfield.update',
    {
        id: 536,
        fields: {
            MANDATORY: "N",
            SHOW_FILTER: "N",
            SETTINGS: {
                DEFAULT_VALUE: "Привет, мир! Значение по умолчанию (изменено)",
                ROWS: 10,
            },
            SORT: 2000,
            EDIT_IN_LIST: "N",
            LIST_FILTER_LABEL: "Привет, мир! Фильтр (изменено)",
            LIST_COLUMN_LABEL: {
                "en": "Hello, World! Column (changed)",
                "ru": "Привет, мир! Колонка (изменено)",
                "de": "Hallo, Welt! Spalte (geändert)"
            },
            EDIT_FORM_LABEL: {
                "en": "Hello, World! Edit (changed)",
                "ru": "Привет, мир! Редактировать (изменено)",
                "de": "Hallo, Welt! Bearbeiten (geändert)"
            },
            ERROR_MESSAGE: {
                "en": "Hello, World! Error (changed)",
                "ru": "Привет, мир! Ошибка (изменено)",
                "de": "Hallo, Welt! Fehler (geändert)"
            },
            HELP_MESSAGE: {
                "en": "Hello, World! Help (changed)",
                "ru": "Привет, мир! Помощь (изменено)",
                "de": "Hallo, Welt! Hilfe (geändert)"
            },
        },
    },
    (result) => {
        result.error()
            ? console.error(result.error())
            : console.info(result.data())
        ;
    },
);
```

### PHP

```php
require_once('crest.php');

$result = CRest::call(
    'crm.deal.userfield.update',
    [
        'id' => 536,
        'fields' => [
            'MANDATORY' => "N",
            'SHOW_FILTER' => "N",
            'SETTINGS' => [
                'DEFAULT_VALUE' => "Привет, мир! Значение по умолчанию (изменено)",
                'ROWS' => 10,
            ],
            'SORT' => 2000,
            'EDIT_IN_LIST' => "N",
            'LIST_FILTER_LABEL' => "Привет, мир! Фильтр (изменено)",
            'LIST_COLUMN_LABEL' => [
                'en' => "Hello, World! Column (changed)",
                'ru' => "Привет, мир! Колонка (изменено)",
                'de' => "Hallo, Welt! Spalte (geändert)"
            ],
            'EDIT_FORM_LABEL' => [
                'en' => "Hello, World! Edit (changed)",
                'ru' => "Привет, мир! Редактировать (изменено)",
                'de' => "Hallo, Welt! Bearbeiten (geändert)"
            ],
            'ERROR_MESSAGE' => [
                'en' => "Hello, World! Error (changed)",
                'ru' => "Привет, мир! Ошибка (изменено)",
                'de' => "Hallo, Welt! Fehler (geändert)"
            ],
            'HELP_MESSAGE' => [
                'en' => "Hello, World! Help (changed)",
                'ru' => "Привет, мир! Помощь (изменено)",
                'de' => "Hallo, Welt! Hilfe (geändert)"
            ],
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
```

### Python

```python
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.crm.deal.userfield.update(
        bitrix_id=536,
        fields={
            "MANDATORY": "N",
            "SHOW_FILTER": "N",
            "SETTINGS": {
                "DEFAULT_VALUE": "Привет, мир! Значение по умолчанию (изменено)",
                "ROWS": 10,
            },
            "SORT": 2000,
            "EDIT_IN_LIST": "N",
            "LIST_FILTER_LABEL": "Привет, мир! Фильтр (изменено)",
            "LIST_COLUMN_LABEL": {
                "en": "Hello, World! Column (changed)",
                "ru": "Привет, мир! Колонка (изменено)",
                "de": "Hallo, Welt! Spalte (geändert)",
            },
            "EDIT_FORM_LABEL": {
                "en": "Hello, World! Edit (changed)",
                "ru": "Привет, мир! Редактировать (изменено)",
                "de": "Hallo, Welt! Bearbeiten (geändert)",
            },
            "ERROR_MESSAGE": {
                "en": "Hello, World! Error (changed)",
                "ru": "Привет, мир! Ошибка (изменено)",
                "de": "Hallo, Welt! Fehler (geändert)",
            },
            "HELP_MESSAGE": {
                "en": "Hello, World! Help (changed)",
                "ru": "Привет, мир! Помощь (изменено)",
                "de": "Hallo, Welt! Hilfe (geändert)",
            },
        },
    ).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}")
```

### Go

```go
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "crm.deal.userfield.update", b24.Params{
	"id": 536,
	"fields": b24.Params{
		"MANDATORY":   "N",
		"SHOW_FILTER": "N",
		"SETTINGS": b24.Params{
			"DEFAULT_VALUE": "Привет, мир! Значение по умолчанию (изменено)",
			"ROWS":          10,
		},
		"SORT":              2000,
		"EDIT_IN_LIST":      "N",
		"LIST_FILTER_LABEL": "Привет, мир! Фильтр (изменено)",
		"LIST_COLUMN_LABEL": b24.Params{
			"en": "Hello, World! Column (changed)",
			"ru": "Привет, мир! Колонка (изменено)",
			"de": "Hallo, Welt! Spalte (geändert)",
		},
		"EDIT_FORM_LABEL": b24.Params{
			"en": "Hello, World! Edit (changed)",
			"ru": "Привет, мир! Редактировать (изменено)",
			"de": "Hallo, Welt! Bearbeiten (geändert)",
		},
		"ERROR_MESSAGE": b24.Params{
			"en": "Hello, World! Error (changed)",
			"ru": "Привет, мир! Ошибка (изменено)",
			"de": "Hallo, Welt! Fehler (geändert)",
		},
		"HELP_MESSAGE": b24.Params{
			"en": "Hello, World! Help (changed)",
			"ru": "Привет, мир! Помощь (изменено)",
			"de": "Hallo, Welt! Hilfe (geändert)",
		},
	},
})
if err != nil {
	return fmt.Errorf("crm.deal.userfield.update: %w", err)
}

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

Оригинал в официальной документации: https://apidocs.bitrix24.ru/api-reference/crm/deals/user-defined-fields/crm-deal-userfield-update.html