# crm.contact.userfield.update

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

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

## Описание

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

## Параметры

- `id` `integer` — обязательный. Идентификатор пользовательского поля.
  Идентификатор можно получить с помощью методов [`crm.contact.userfield.add`](https://chugunov.pro/api-bitrix24/crm/contacts/userfield/crm-contact-userfield-add/) и [`crm.contact.userfield.list`](https://chugunov.pro/api-bitrix24/crm/contacts/userfield/crm-contact-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`. Для пользовательских полей другого типа данный параметр не несет смысла
- `SORT` `integer` — необязательный. Индекс сортировки. Обязательно больше нуля
- `SHOW_IN_LIST` `boolean` — необязательный. Показывать ли пользовательское поле в списке.
  Данный параметр ни на что не влияет в рамках `crm`.
  Возможные значения:
  - `Y` — да
  - `N` — нет
- `EDIT_IN_LIST` `boolean` — необязательный. Разрешать ли редактирование пользователем. Возможные значения:
  - `Y` — да
  - `N` — нет
- `IS_SEARCHABLE` `boolean` — необязательный. Участвуют ли значения поля в поиске.
  Данный параметр ни на что не влияет в рамках `crm`.
  Возможные значения:
  - `Y` — да
  - `N` — нет
- `LIST_FILTER_LABEL` `string` — необязательный. Подпись фильтра в списке.
  При передаче строки она устанавливается для каждого языка.
  Для языков, у которых явно не указано значение, будет записано `''`.
  Поле полностью перезаписывает предыдущее значение
- `LIST_COLUMN_LABEL` `string` — необязательный. Заголовок в списке.
  При передаче строки она устанавливается для каждого языка.
  Для языков, у которых явно не указано значение, будет записано `''`.
  Поле полностью перезаписывает предыдущее значение
- `EDIT_FORM_LABEL` `string` — необязательный. Подпись в форме редактирования.
  При передаче строки она устанавливается для каждого языка.
  Для языков, у которых явно не указано значение, будет записано `''`.
  Поле полностью перезаписывает предыдущее значение
- `ERROR_MESSAGE` `string` — необязательный. Сообщение об ошибке.
  При передаче строки она устанавливается для каждого языка.
  Для языков, у которых явно не указано значение, будет записано `''`.
  Поле полностью перезаписывает предыдущее значение
- `HELP_MESSAGE` `string` — необязательный. Помощь.
  При передаче строки она устанавливается для каждого языка.
  Для языков, у которых явно не указано значение, будет записано `''`.
  Поле полностью перезаписывает предыдущее значение

### Тип uf_enum_element

- `ID` `string` — необязательный. Идентификатор элемента списка. При передаче данного параметра будет изменен соответствующий элемент списка, иначе будет добавлен новый элемент списка.
  Идентификатор можно узнать с помощью метода [`crm.contact.userfield.get`](https://chugunov.pro/api-bitrix24/crm/contacts/userfield/crm-contact-userfield-get/#uf_enum_element)
- `DEL` `boolean` — необязательный. Флаг, необходимый для удаления элемента списка. Имеет смысл лишь при передаче `ID`.
  Возможные значения:
  `Y` — удалить
  `N` — не удалять
  По умолчанию `N`
- `VALUE` `string` — необязательный. Значение элемента списка
- `SORT` `integer` — необязательный. Индекс сортировки. Обязательно больше или равно 0
- `DEF` `boolean` — необязательный. Является ли элемент списка значением по умолчанию. Возможные значения:
  - `Y` — да
  - `N` — нет
  Для множественного поля допустимо несколько `DEF = Y`. Для не множественного значением по умолчанию будет считаться первый переданный элемент списка с `DEF = Y`
- `XML_ID` `string` — необязательный. Внешний код значения. Обязательно уникальный в рамках элементов списка пользовательского поля

## Ответ

HTTP-статус: 200

```json
{
    "result": true,
    "time": {
        "start": 1724419843.518672,
        "finish": 1724419844.120328,
        "duration": 0.6016559600830078,
        "processing": 0.1907808780670166,
        "date_start": "2024-08-23T15:30:43+02:00",
        "date_finish": "2024-08-23T15:30:44+02:00",
        "operating": 0
    }
}
```

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

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

## Ошибки

HTTP-статус: 400

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

- — — `Parameter 'fields' must be array`. Переданный `fields` не является объектом
- — — `ID is not defined or invalid`. Переданный `id` меньше нуля или не передан вовсе
- — — `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.contact.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.contact.userfield.update
```

### BX24.js

```js
BX24.callMethod(
    'crm.contact.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
try {
    $contactUserfieldItemId = 123; // Example ID
    $userfieldFieldsToUpdate = [
        'FIELD_NAME' => 'New Field Name',
        'USER_TYPE_ID' => 'string',
        'SORT' => '100',
        'MULTIPLE' => 'N',
        'MANDATORY' => 'N',
        'SHOW_FILTER' => 'Y',
        'SHOW_IN_LIST' => 'Y',
        'EDIT_IN_LIST' => 'Y',
        'IS_SEARCHABLE' => 'Y',
        'EDIT_FORM_LABEL' => 'New Label',
        'LIST_COLUMN_LABEL' => 'Column Label',
        'LIST_FILTER_LABEL' => 'Filter Label',
        'ERROR_MESSAGE' => 'Error Message',
        'HELP_MESSAGE' => 'Help Message',
        'LIST' => '',
        'SETTINGS' => '',
    ];

    $result = $serviceBuilder
        ->getCRMScope()
        ->contactUserfield()
        ->update($contactUserfieldItemId, $userfieldFieldsToUpdate);

    if ($result->isSuccess()) {
        print($result->getCoreResponse()->getResponseData()->getResult()[0]);
    } else {
        print("Update failed.");
    }
} catch (Throwable $e) {
    print("Error: " . $e->getMessage());
}
```

### PHP CRest

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

$result = CRest::call(
    'crm.contact.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.contact.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.contact.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.contact.userfield.update: %w", err)
}

// Ответ приходит как json.RawMessage — разберите его
// в структуру под форму ответа, показанную ниже на этой странице.
fmt.Printf("%s\n", res.Result)
```

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