# crm.deal.userfield.add

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

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

## Описание

Метод `crm.deal.userfield.add` создает новое пользовательское поле для сделок.

## Параметры

- `fields` `object` — обязательный. Объект формата:
  ```
  {
      field_1: value_1,
      field_2: value_2,
      ...,
      field_n: value_n,
  }
  ```
  - `field_n` — название поля
  - `value_n` — значение поля
  Список доступных полей описан [ниже](#parameter-fields).
  Некорректное поле в `fields` будет проигнорировано

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

- `USER_TYPE_ID` `string` — обязательный. Тип данных пользовательского поля. Возможные значения:
  - `string` — строка
  - `integer` — целое число
  - `double` — число
  - `boolean` — да/нет
  - `datetime` — дата/время
  - `date` — дата
  - `money` — деньги
  - `url` — ссылка
  - `address` — адрес
  - `enumeration` — список
  - `file` — файл
  - `employee` — привязка к сотруднику
  - `crm_status` — привязка к справочнику CRM
  - `iblock_section` — привязка к разделам инф. блоков
  - `iblock_element` — привязка к элементам инф. блоков
  - `crm` — привязка к элементам CRM
  - [пользовательские типы полей](https://apidocs.bitrix24.ru/api-reference/crm/universal/user-defined-fields/userfield-type.html)
- `FIELD_NAME` `string` — обязательный. Код поля. Уникальный в пределах сделок.
  К коду всегда добавляется префикс `UF_CRM_`, полное имя поля система собирает сама:
  - `MANAGER_NOTE` превращается в `UF_CRM_MANAGER_NOTE`
  - `UF_MANAGER_NOTE` превращается в `UF_CRM_MANAGER_NOTE` — префикс `UF_` заменяется на `UF_CRM_`
  - `UF_CRM_MANAGER_NOTE` остается без изменений
  Ограничение длины — до `50` символов вместе с префиксом, то есть до `43` символов на код. Если передать более длинное значение, метод вернет ошибку `ERROR_CORE`.
  Допустимые символы: `A-Z`, `0-9` и `_`. Строчные буквы приводятся к заглавным, остальные символы вызывают ошибку `ERROR_CORE`
- `LABEL` `string` — необязательный. Название пользовательского поля по умолчанию.
  Переданное значение будет выставлено в следующие поля: `LIST_FILTER_LABEL`, `LIST_COLUMN_LABEL`, `EDIT_FORM_LABEL`, `ERROR_MESSAGE`, `HELP_MESSAGE`, если в них не передано значение
- `XML_ID` `string` — необязательный. Внешний код
- `LIST_FILTER_LABEL` `string` — необязательный. Подпись фильтра в списке.
  При передаче строки она будет проставлена для всех идентификаторов языка.
  При передаче значения типа `lang_map` для всех непереданных языков будет проставлено значение из `LABEL`.
  По умолчанию значение, переданное в `LABEL`, проставляется для всех идентификаторов языка
- `LIST_COLUMN_LABEL` `string` — необязательный. Заголовок в списке.
  При передаче строки она будет проставлена для всех идентификаторов языка.
  При передаче значения типа `lang_map` для всех непереданных языков будет проставлено значение из `LABEL`.
  По умолчанию значение, переданное в `LABEL`, проставляется для всех идентификаторов языка
- `EDIT_FORM_LABEL` `string` — необязательный. Подпись в форме редактирования.
  При передаче строки она будет проставлена для всех идентификаторов языка.
  При передаче значения типа `lang_map` для всех непереданных языков будет проставлено значение из `LABEL`.
  По умолчанию значение, переданное в `LABEL`, проставляется для всех идентификаторов языка
- `ERROR_MESSAGE` `string` — необязательный. Сообщение об ошибке
- `HELP_MESSAGE` `string` — необязательный. Помощь
- `MULTIPLE` `boolean` — необязательный. Является ли поле множественным. Возможные значения:
  - `Y` — да
  - `N` — нет
  Поля типа `boolean` не могут быть множественными.
  По умолчанию `N`
- `MANDATORY` `boolean` — необязательный. Является ли поле обязательным. Возможные значения:
  - `Y` — да
  - `N` — нет
  По умолчанию `N`
- `SHOW_FILTER` `boolean` — необязательный. Показывать ли поле в фильтре. Возможные значения:
  - `Y` — да
  - `N` — нет
  По умолчанию `N`
- `SETTINGS` `object` — необязательный. Дополнительные параметры поля. Для каждого типа поля `USER_TYPE_ID` существует свой пул доступных настроек, описание [ниже](#settings)
- `LIST` `uf_enum_element[]` — необязательный. Список возможных значений для пользовательского поля типа `enumeration`, описание [ниже](#uf_enum_element)
  По умолчанию `[]`
- `SORT` `integer` — необязательный. Индекс сортировки. Обязательно больше нуля.
  По умолчанию `100`
- `SHOW_IN_LIST` `boolean` — необязательный. Показывать ли пользовательское поле в списке.
  Данный параметр ни на что не влияет в рамках `crm`.
  Возможные значения:
  - `Y` — да
  - `N` — нет
  По умолчанию `N`
- `EDIT_IN_LIST` `boolean` — необязательный. Разрешать ли редактирование пользователем. Возможные значения:
  - `Y` — да
  - `N` — нет
  По умолчанию `Y`. Значение `N` поддерживают не все типы полей в рамках `crm`
- `IS_SEARCHABLE` `boolean` — необязательный. Участвуют ли значения поля в поиске.
  Данный параметр ни на что не влияет в рамках `crm`.
  Возможные значения:
  - `Y` — да
  - `N` — нет
  По умолчанию `N`

## Ответ

HTTP-статус: 200

```json
{
    "result": 6997,
    "time": {
        "start": 1753789240.8146,
        "finish": 1753789241.058695,
        "duration": 0.2440950870513916,
        "processing": 0.19217395782470703,
        "date_start": "2025-07-29T14:40:40+03:00",
        "date_finish": "2025-07-29T14:40:41+03:00",
        "operating_reset_at": 1753789840,
        "operating": 0.19216084480285645
    }
}
```

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

- `result` `integer`. Корневой элемент ответа, содержит идентификатор созданного пользовательского поля
- `time` `time`. Информация о времени выполнения запроса

## Ошибки

HTTP-статус: 400

```json
{
    "error": "",
    "error_description": "The 'USER_TYPE_ID' field is not found."
}
```

- — — `The 'FIELD_NAME' field is not found.`. Либо передан пустой `FIELD_NAME`, либо он не передан вовсе
- `ERROR_CORE` — `Имя поля слишком длинное (больше 50-ти символов).`. Полное имя поля вместе с префиксом `UF_CRM_` содержит более 50 символов, то есть в `FIELD_NAME` передано более 43 символов
- `ERROR_CORE` — `Имя поля содержит недопустимые символы. Допустимыми являются: A-Z, 0-9 и _.`. Переданный `FIELD_NAME` содержит символы, кроме `A-Z`, `0-9` и `_`
- — — `The 'USER_TYPE_ID' field is not found.`. Либо передан пустой `USER_TYPE_ID`, либо он не передан вовсе
- `ERROR_CORE` — `Указан неверный пользовательский тип.`. Переданный `USER_TYPE_ID` не существует
- `ERROR_CORE` — `Элемент списка со значением XML_ID=xml_id уже существует.`. Переданные в элементы списка `XML_ID` не уникальны

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