# crm.contact.userfield.add

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

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

## Описание

Метод `crm.contact.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` — необязательный. Сообщение об ошибке.
  При передаче строки она будет проставлена для всех идентификаторов языка.
  При передаче значения типа `lang_map` для всех непереданных языков будет проставлено значение из `LABEL`.
  По умолчанию значение, переданное в `LABEL`, проставляется для всех идентификаторов языка
- `HELP_MESSAGE` `string` — необязательный. Помощь.
  При передаче строки она будет проставлена для всех идентификаторов языка.
  При передаче значения типа `lang_map` для всех непереданных языков будет проставлено значение из `LABEL`.
  По умолчанию значение, переданное в `LABEL`, проставляется для всех идентификаторов языка
- `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`. Для пользовательских полей другого типа данный параметр не несет смысла.
  По умолчанию `[]`
- `SORT` `integer` — необязательный. Индекс сортировки. Обязательно больше нуля.
  По умолчанию `100`
- `SHOW_IN_LIST` `boolean` — необязательный. Показывать ли пользовательское поле в списке.
  Данный параметр ни на что не влияет в рамках `crm`.
  Возможные значения:
  - `Y` — да
  - `N` — нет
  По умолчанию `N`
- `EDIT_IN_LIST` `boolean` — необязательный. Разрешать ли редактирование пользователем. Возможные значения:
  - `Y` — да
  - `N` — нет
  По умолчанию `Y`
- `IS_SEARCHABLE` `boolean` — необязательный. Участвуют ли значения поля в поиске.
  Данный параметр ни на что не влияет в рамках `crm`.
  Возможные значения:
  - `Y` — да
  - `N` — нет
  По умолчанию `N`

### Тип uf_enum_element

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

## Ответ

HTTP-статус: 200

```json
{
    "result": 399,
    "time": {
        "start": 1724239307.903115,
        "finish": 1724239308.567422,
        "duration": 0.6643068790435791,
        "processing": 0.20090818405151367,
        "date_start": "2024-08-21T13:21:47+02:00",
        "date_finish": "2024-08-21T13:21:48+02:00",
        "operating": 0
    }
}
```

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

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

## Ошибки

HTTP-статус: 400

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

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

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

### cURL (Webhook)

```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"LABEL":"Поле \'Привет, мир!\'","USER_TYPE_ID":"string","FIELD_NAME":"HELLO_WORLD","MULTIPLE":"Y","MANDATORY":"Y","SHOW_FILTER":"Y","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию","ROWS":3},"SORT":1000,"EDIT_IN_LIST":"Y","LIST_FILTER_LABEL":"Привет, мир! Фильтр","LIST_COLUMN_LABEL":{"en":"Hello, World! Column","ru":"Привет, мир! Колонка","de":"Hallo, Welt! Spalte"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit","ru":"Привет, мир! Редактировать","de":"Hallo, Welt! Bearbeiten"},"ERROR_MESSAGE":{"en":"Hello, World! Error","ru":"Привет, мир! Ошибка","de":"Hallo, Welt! Fehler"},"HELP_MESSAGE":{"en":"Hello, World! Help","ru":"Привет, мир! Помощь","de":"Hallo, Welt! Hilfe"}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.contact.userfield.add
```

### cURL (OAuth)

```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"LABEL":"Поле \'Привет, мир!\'","USER_TYPE_ID":"string","FIELD_NAME":"HELLO_WORLD","MULTIPLE":"Y","MANDATORY":"Y","SHOW_FILTER":"Y","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию","ROWS":3},"SORT":1000,"EDIT_IN_LIST":"Y","LIST_FILTER_LABEL":"Привет, мир! Фильтр","LIST_COLUMN_LABEL":{"en":"Hello, World! Column","ru":"Привет, мир! Колонка","de":"Hallo, Welt! Spalte"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit","ru":"Привет, мир! Редактировать","de":"Hallo, Welt! Bearbeiten"},"ERROR_MESSAGE":{"en":"Hello, World! Error","ru":"Привет, мир! Ошибка","de":"Hallo, Welt! Fehler"},"HELP_MESSAGE":{"en":"Hello, World! Help","ru":"Привет, мир! Помощь","de":"Hallo, Welt! Hilfe"}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.contact.userfield.add
```

### BX24.js

```js
BX24.callMethod(
    'crm.contact.userfield.add',
    {
        fields: {
            LABEL: "Поле \'Привет, мир!\'",
            USER_TYPE_ID: "string",
            FIELD_NAME: "HELLO_WORLD",
            MULTIPLE: "Y",
            MANDATORY: "Y",
            SHOW_FILTER: "Y",
            SETTINGS: {
                DEFAULT_VALUE: "Привет, мир! Значение по умолчанию",
                ROWS: 3,
            },
            SORT: 1000,
            EDIT_IN_LIST: "Y",
            LIST_FILTER_LABEL: "Привет, мир! Фильтр",
            LIST_COLUMN_LABEL: {
                "en": "Hello, World! Column",
                "ru": "Привет, мир! Колонка",
                "de": "Hallo, Welt! Spalte"
            },
            EDIT_FORM_LABEL: {
                "en": "Hello, World! Edit",
                "ru": "Привет, мир! Редактировать",
                "de": "Hallo, Welt! Bearbeiten"
            },
            ERROR_MESSAGE: {
                "en": "Hello, World! Error",
                "ru": "Привет, мир! Ошибка",
                "de": "Hallo, Welt! Fehler"
            },
            HELP_MESSAGE: {
                "en": "Hello, World! Help",
                "ru": "Привет, мир! Помощь",
                "de": "Hallo, Welt! Hilfe"
            },
        },
    },
    (result) => {
        result.error()
            ? console.error(result.error())
            : console.info(result.data())
        ;
    },
);
```

### PHP

```php
try {
    $userfieldItemFields = [
        'FIELD_NAME' => 'UF_CRM_example',
        'USER_TYPE_ID' => 'string',
        'XML_ID' => 'xml_example',
        'SORT' => '100',
        'MULTIPLE' => 'N',
        'MANDATORY' => 'Y',
        'SHOW_FILTER' => 'Y',
        'SHOW_IN_LIST' => 'Y',
        'EDIT_IN_LIST' => 'Y',
        'IS_SEARCHABLE' => 'Y',
        'EDIT_FORM_LABEL' => 'Example Field',
        'LIST_COLUMN_LABEL' => 'Example Column',
        'LIST_FILTER_LABEL' => 'Example Filter',
        'ERROR_MESSAGE' => 'Error occurred',
        'HELP_MESSAGE' => 'Help message',
        'LIST' => 'list_value',
        'SETTINGS' => 'settings_value',
    ];

    $result = $serviceBuilder
        ->getCRMScope()
        ->contactUserfield()
        ->add($userfieldItemFields);

    print($result->getId());
} catch (Throwable $e) {
    print('Error: ' . $e->getMessage());
}
```

### PHP CRest

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

$result = CRest::call(
    'crm.contact.userfield.add',
    [
        'fields' => [
            'LABEL' => "Поле 'Привет, мир!'",
            'USER_TYPE_ID' => "string",
            'FIELD_NAME' => "HELLO_WORLD",
            'MULTIPLE' => "Y",
            'MANDATORY' => "Y",
            'SHOW_FILTER' => "Y",
            'SETTINGS' => [
                'DEFAULT_VALUE' => "Привет, мир! Значение по умолчанию",
                'ROWS' => 3,
            ],
            'SORT' => 1000,
            'EDIT_IN_LIST' => "Y",
            'LIST_FILTER_LABEL' => "Привет, мир! Фильтр",
            'LIST_COLUMN_LABEL' => [
                'en' => "Hello, World! Column",
                'ru' => "Привет, мир! Колонка",
                'de' => "Hallo, Welt! Spalte"
            ],
            'EDIT_FORM_LABEL' => [
                'en' => "Hello, World! Edit",
                'ru' => "Привет, мир! Редактировать",
                'de' => "Hallo, Welt! Bearbeiten"
            ],
            'ERROR_MESSAGE' => [
                'en' => "Hello, World! Error",
                'ru' => "Привет, мир! Ошибка",
                'de' => "Hallo, Welt! Fehler"
            ],
            'HELP_MESSAGE' => [
                'en' => "Hello, World! Help",
                'ru' => "Привет, мир! Помощь",
                'de' => "Hallo, Welt! Hilfe"
            ],
        ]
    ]
);

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

### Python

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

try:
    bitrix_response = client.crm.contact.userfield.add(
        fields={
            "LABEL": "Поле 'Привет, мир!'",
            "USER_TYPE_ID": "string",
            "FIELD_NAME": "HELLO_WORLD",
            "MULTIPLE": "Y",
            "MANDATORY": "Y",
            "SHOW_FILTER": "Y",
            "SETTINGS": {
                "DEFAULT_VALUE": "Привет, мир! Значение по умолчанию",
                "ROWS": 3,
                "DISPLAY": "UI",
                "LIST_HEIGHT": 2,
            },
            "SORT": 1000,
            "EDIT_IN_LIST": "Y",
            "LIST_FILTER_LABEL": "Привет, мир! Фильтр",
            "LIST_COLUMN_LABEL": {
                "en": "Hello, World! Column",
                "ru": "Привет, мир! Колонка",
                "de": "Hallo, Welt! Spalte",
            },
            "EDIT_FORM_LABEL": {
                "en": "Hello, World! Edit",
                "ru": "Привет, мир! Редактировать",
                "de": "Hallo, Welt! Bearbeiten",
            },
            "ERROR_MESSAGE": {
                "en": "Hello, World! Error",
                "ru": "Привет, мир! Ошибка",
                "de": "Hallo, Welt! Fehler",
            },
            "HELP_MESSAGE": {
                "en": "Hello, World! Help",
                "ru": "Привет, мир! Помощь",
                "de": "Hallo, Welt! Hilfe",
            },
            "LIST": [
                {
                    "VALUE": "Элемент списка #1",
                    "DEF": "Y",
                    "XML_ID": "XML_ID_1",
                    "SORT": 100,
                },
                {
                    "VALUE": "Элемент списка #2",
                    "XML_ID": "XML_ID_2",
                    "SORT": 200,
                },
                {
                    "VALUE": "Элемент списка #3",
                    "XML_ID": "XML_ID_3",
                    "SORT": 300,
                },
                {
                    "VALUE": "Элемент списка #4",
                    "XML_ID": "XML_ID_4",
                    "SORT": 400,
                },
            ],
        },
    ).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}")
```

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