# lists.field.add

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

Создать поле универсального списка
Scope: `lists`
Кто может выполнять метод: пользователь с правом «Полный доступ» для нужного списка

## Описание

Метод `lists.field.add` создает поле списка.

Список доступных типов полей для универсального списка можно узнать с помощью метода [lists.field.type.get](https://chugunov.pro/api-bitrix24/lists/fields/lists-field-type-get/)

## Параметры

- `IBLOCK_TYPE_ID` `string` — обязательный. Идентификатор типа инфоблока.
  Стандартные типы:
  - `lists` — универсальные списки
  - `bitrix_processes` — процессы
  - `lists_socnet` — списки групп
  В коробочной версии можно также указать идентификатор произвольного существующего типа инфоблоков. `IBLOCK_ID` или `IBLOCK_CODE` должен указывать на инфоблок этого типа. Доступ к операции определяется стандартными правами пользователя на инфоблок, раздел или элемент
    
  Идентификатор можно получить с помощью метода [lists.get.iblock.type.id](https://chugunov.pro/api-bitrix24/lists/lists/lists-get-iblock-type-id/)
- `IBLOCK_ID` `integer` — обязательный. Идентификатор инфоблока.
  Идентификатор можно получить с помощью метода [lists.get](https://chugunov.pro/api-bitrix24/lists/lists/lists-get/)
- `IBLOCK_CODE` `string` — обязательный. Cимвольный код инфоблока.
  Код можно получить с помощью метода [lists.get](https://chugunov.pro/api-bitrix24/lists/lists/lists-get/)
  Необходимо указать хотя бы один из параметров: `IBLOCK_ID` или `IBLOCK_CODE`
- `FIELDS` `array` — обязательный. Массив параметров.
  [Подробное описание](#parametr-fields)

### Параметр FIELDS

- `NAME` `string` — обязательный. Название поля
- `TYPE` `string` — обязательный. Тип поля. После создания тип поля изменить будет нельзя.
  Пользовательские поля:
  - `S` — Строка
  - `N` — Число
  - `L` — Список
  - `F` — Файл
  - `G` — Привязка к разделам
  - `E` — Привязка к элементам
  - `S:Date` — Дата
  - `S:DateTime` — Дата/Время
  - `S:HTML` — HTML/текст
  - `E:EList` — Привязка к элементам в виде списка
  - `N:Sequence` — Счетчик
  - `S:ECrm` — Привязка к элементам CRM 
  - `S:Money` — Деньги
  - `S:DiskFile` — Файл (Диск)
  - `S:map_yandex` — Привязка к Яндекс.Карте
  - `S:employee` — Привязка к сотруднику
  Системные поля:
  - `SORT` — Сортировка
  - `ACTIVE_FROM` — Начало активности
  - `ACTIVE_TO` — Окончание активности
  - `PREVIEW_PICTURE` — Изображение для анонса
  - `PREVIEW_TEXT` — Текст анонса
  - `DETAIL_PICTURE` — Детальное изображение
  - `DETAIL_TEXT` — Детальный текст
  - `DATE_CREATE` — Дата создания
  - `CREATED_BY` — Кем создан
  - `TIMESTAMP_X` — Дата изменения
  - `MODIFIED_BY` — Кем изменен
    
  Значения в полях Дата создания, Дата изменения, Кем создан и Кем изменен заполняются автоматически
  Системные поля не добавляются в новый список по умолчанию. Чтобы они отображались в интерфейсе списка, их также необходимо явно создать
- `IS_REQUIRED` `string` — необязательный. Флаг обязательности поля. Возможные значения:
  - `Y` — да
  - `N` — нет
    
  По умолчанию — `N`
- `MULTIPLE` `string` — необязательный. Флаг множественности поля. Возможные значения:
  - `Y` — да
  - `N` — нет  
  По умолчанию — `N`.
  Системные поля и поле типа Привязка к Яндекс.Карте не могут быть множественными
- `SORT` `integer` — необязательный. Сортировка
- `DEFAULT_VALUE` — необязательный. Значение по умолчанию. Если включена настройка `ADD_READ_ONLY_FIELD` в `SETTINGS`, параметр становится обязательным
- `LIST` `array` — необязательный. Значения для поля типа Список. Массив в формате `{'ID': { 'VALUE': 'Value_1', 'SORT': 10, 'DEF': 'N' }}`, где `'ID'` — временный идентификатор, `VALUE` — отображаемый текст, `SORT` — порядок сортировки, `DEF` — признак значения по умолчанию.
  После создания поля система заменит временные идентификаторы на постоянные
- `LIST_TEXT_VALUES` `string` — необязательный. Альтернативный способ задания значений для поля типа Список. Строка, где значения разделены символом переноса `\n`
  При создании поля типа Список можно использовать либо `LIST`, либо `LIST_TEXT_VALUES`, либо оба параметра вместе. В этом случае значения из строки добавятся к тем, что уже есть в массиве
- `LIST_DEF` `array` — необязательный. Значение по умолчанию для поля типа Список. Массив принимает временный идентификатор из `LIST`
- `CODE` `string` — необязательный. Символьный код поля. Обязателен для пользовательских полей. Для системных полей не используется
- `SETTINGS` `array` — необязательный. Настройки отображения и поведения.
  Поддерживаются значения:
  - `SHOW_ADD_FORM` — показывать в форме добавления
  - `SHOW_EDIT_FORM` — показывать в форме редактирования
  - `ADD_READ_ONLY_FIELD` — только для чтения (форма добавления)
  - `EDIT_READ_ONLY_FIELD` — только для чтения (форма редактирования)
  - `SHOW_FIELD_PREVIEW` — показать поле при формировании ссылки на элемент списка
    
  Для включения настройки используйте `Y`, для выключения — `N`.
  По умолчанию: `SHOW_ADD_FORM` — `Y`, `SHOW_EDIT_FORM` — `Y`, `ADD_READ_ONLY_FIELD` — `N`, `EDIT_READ_ONLY_FIELD` — `N`, `SHOW_FIELD_PREVIEW` — `N`
- `USER_TYPE_SETTINGS` `array` — необязательный. Массив настроек для пользовательских полей. Структура зависит от типа поля:
  - HTML/текст — массив в формате `{'height': 200}`, где `height` — высота окна редактора	
  - Привязка к элементам в виде списка — массив в формате `{'size': 1, 'width': 0, 'group': 'N', 'multiple': 'N'}`, где `size` — высота списка, `width` — ограничение по ширине (`0` - не ограничивать), `group` — группировка по разделам, `multiple` — отображение в виде списка множественного выбора
  - Счетчик — массив в формате `{'write': 'N', 'VALUE': 1}`, где `write` — разрешение изменять значения, `VALUE` — текущее значение счетчика
  - Привязка к элементам CRM — массив в формате `{'VISIBLE': 'N', 'LEAD': 'N', 'CONTACT': 'N', 'COMPANY': 'N', 'DEAL': 'N'}`, где `VISIBLE` — видимость в карточке CRM, `LEAD` — лид, `CONTACT` — контакт, `COMPANY` — компания, `DEAL` — сделка 
  Если не передавать — система установит значения по умолчанию, которые указаны в примерах массивов
- `ROW_COUNT` `integer` — необязательный. Высота поля.
  По умолчанию — `1`
- `COL_COUNT` `integer` — необязательный. Ширина поля.
  По умолчанию — `30`
- `LINK_IBLOCK_ID` `integer` — необязательный. Идентификатор связанного списка. Обязателен для типов Привязка к разделам, Привязка к элементам и Привязка к элементам в виде списка

## Ответ

HTTP-статус: 200

```json
{
    "result": "PROPERTY_1151",
    "time": {
        "start": 1765317940,
        "finish": 1765317940.172892,
        "duration": 0.17289209365844727,
        "processing": 0,
        "date_start": "2025-12-09T14:05:40+03:00",
        "date_finish": "2025-12-09T14:05:40+03:00",
        "operating_reset_at": 1765318540,
        "operating": 0
    }
}
```

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

- `result` `string`. Идентификатор созданного поля с приставкой `PROPERTY_`.
  Если создается системное поле, возвращается его символьный код
- `time` `time`. Информация о времени выполнения запроса

## Ошибки

HTTP-статус: 400

```json
{
    "error":"ERROR_SAVE_FIELD",
    "error_description":"Please fill the code fields"
}
```

- `ERROR_REQUIRED_PARAMETERS_MISSING` — Required parameter `X` is missing. Обязательный параметр не передан
- `ERROR_IBLOCK_NOT_FOUND` — Iblock not found. Инфоблок не найден
- `ERROR_SAVE_FIELD` — Error saving the field. Общая ошибка при вызове
- `ERROR_SAVE_FIELD` — Property already exists. `CODE` уже используется в списке
- `ERROR_SAVE_FIELD` — Please fill the code fields. Не указан `CODE` для пользовательского поля
- `ERROR_SAVE_FIELD` — The default value of the field '...' is required. Включена настройка `ADD_READ_ONLY_FIELD`, но не указано `DEFAULT_VALUE`
- `ERROR_SAVE_FIELD` — Incorrect lists specified for '...' property. Ошибка в одном из параметров внутри `FIELDS`
- `ACCESS_DENIED` — Access denied. Недостаточно прав для добавления поля

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

### cURL (Webhook)

```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"IBLOCK_TYPE_ID":"lists","IBLOCK_ID":"123","FIELDS":{"NAME":"Проект","IS_REQUIRED":"Y","MULTIPLE":"N","TYPE":"L","SORT":"10","CODE":"PROJECT","LIST":{"10":{"VALUE":"Планирование","SORT":10,"DEF":"Y"},"20":{"VALUE":"В разработке","SORT":20,"DEF":"N"}},"LIST_TEXT_VALUES":"Тестирование\nЗавершен\nОтложен","SETTINGS":{"SHOW_ADD_FORM":"Y","SHOW_EDIT_FORM":"Y","ADD_READ_ONLY_FIELD":"N","EDIT_READ_ONLY_FIELD":"N","SHOW_FIELD_PREVIEW":"N"}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/lists.field.add
```

### cURL (OAuth)

```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"IBLOCK_TYPE_ID":"lists","IBLOCK_ID":"123","FIELDS":{"NAME":"Проект","IS_REQUIRED":"Y","MULTIPLE":"N","TYPE":"L","SORT":"10","CODE":"PROJECT","LIST":{"10":{"VALUE":"Планирование","SORT":10,"DEF":"Y"},"20":{"VALUE":"В разработке","SORT":20,"DEF":"N"}},"LIST_TEXT_VALUES":"Тестирование\nЗавершен\nОтложен","SETTINGS":{"SHOW_ADD_FORM":"Y","SHOW_EDIT_FORM":"Y","ADD_READ_ONLY_FIELD":"N","EDIT_READ_ONLY_FIELD":"N","SHOW_FIELD_PREVIEW":"N"}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/lists.field.add
```

### JS (TS)

```ts
// 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

try {
  const response = await $b24.actions.v2.call.make<string>({
    method: 'lists.field.add',
    params: {
      IBLOCK_TYPE_ID: 'lists',
      IBLOCK_ID: '123',
      FIELDS: {
        NAME: 'Project',
        IS_REQUIRED: 'Y',
        MULTIPLE: 'N',
        TYPE: 'L',
        SORT: '10',
        CODE: 'PROJECT',
        LIST: {
          '10': { VALUE: 'Planning', SORT: 10, DEF: 'Y' },
          '20': { VALUE: 'In progress', SORT: 20, DEF: 'N' },
        },
        LIST_TEXT_VALUES: 'Testing\nCompleted\nPostponed',
        SETTINGS: {
          SHOW_ADD_FORM: 'Y',
          SHOW_EDIT_FORM: 'Y',
          ADD_READ_ONLY_FIELD: 'N',
          EDIT_READ_ONLY_FIELD: 'N',
          SHOW_FIELD_PREVIEW: 'N',
        },
      },
    },
    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('Created field ID:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
```

### JS (UMD)

```html
<!-- 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 addListField() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'lists.field.add',
        params: {
          IBLOCK_TYPE_ID: 'lists',
          IBLOCK_ID: '123',
          FIELDS: {
            NAME: 'Project',
            IS_REQUIRED: 'Y',
            MULTIPLE: 'N',
            TYPE: 'L',
            SORT: '10',
            CODE: 'PROJECT',
            LIST: {
              '10': { VALUE: 'Planning', SORT: 10, DEF: 'Y' },
              '20': { VALUE: 'In progress', SORT: 20, DEF: 'N' },
            },
            LIST_TEXT_VALUES: 'Testing\nCompleted\nPostponed',
            SETTINGS: {
              SHOW_ADD_FORM: 'Y',
              SHOW_EDIT_FORM: 'Y',
              ADD_READ_ONLY_FIELD: 'N',
              EDIT_READ_ONLY_FIELD: 'N',
              SHOW_FIELD_PREVIEW: 'N',
            },
          },
        },
        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('Created field ID:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addListField)
</script>
```

### Python

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

fields = {
    "NAME": "Проект",
    "IS_REQUIRED": "Y",
    "MULTIPLE": "N",
    "TYPE": "L",
    "SORT": "10",
    "CODE": "PROJECT",
    "LIST": {
        "10": {
            "VALUE": "Планирование",
            "SORT": 10,
            "DEF": "Y",
        },
        "20": {
            "VALUE": "В разработке",
            "SORT": 20,
            "DEF": "N",
        },
    },
    "LIST_TEXT_VALUES": "Тестирование\nЗавершен\nОтложен",
    "SETTINGS": {
        "SHOW_ADD_FORM": "Y",
        "SHOW_EDIT_FORM": "Y",
        "ADD_READ_ONLY_FIELD": "N",
        "EDIT_READ_ONLY_FIELD": "N",
        "SHOW_FIELD_PREVIEW": "N",
    },
}

try:
    bitrix_response = client.lists.field.add(
        iblock_type_id="lists",
        iblock_id=123,
        fields=fields,
    ).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}")
```

### PHP

```php
try {
    $response = $b24Service
        ->core
        ->call(
            'lists.field.add',
            [
                'IBLOCK_TYPE_ID' => 'lists',
                'IBLOCK_ID' => '123',
                'FIELDS' => [
                    'NAME' => 'Проект',
                    'IS_REQUIRED' => 'Y',
                    'MULTIPLE' => 'N',
                    'TYPE' => 'L',
                    'SORT' => '10',
                    'CODE' => 'PROJECT',
                    'LIST' => [
                        '10' => ['VALUE' => 'Планирование', 'SORT' => 10, 'DEF' => 'Y'],
                        '20' => ['VALUE' => 'В разработке', 'SORT' => 20, 'DEF' => 'N']
                    ],
                    'LIST_TEXT_VALUES' => 'Тестирование\nЗавершен\nОтложен',
                    'SETTINGS' => [
                        'SHOW_ADD_FORM' => 'Y',
                        'SHOW_EDIT_FORM' => 'Y',
                        'ADD_READ_ONLY_FIELD' => 'N',
                        'EDIT_READ_ONLY_FIELD' => 'N',
                        'SHOW_FIELD_PREVIEW' => 'N'
                    ]
                ]
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);
    processData($result);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error adding field: ' . $e->getMessage();
}
```

### BX24.js

```js
BX24.callMethod(
    'lists.field.add',
    {
        'IBLOCK_TYPE_ID': 'lists',
        'IBLOCK_ID': '123',
        'FIELDS': {
            'NAME': 'Проект',
            'IS_REQUIRED': 'Y',
            'MULTIPLE': 'N',
            'TYPE': 'L',
            'SORT': '10',
            'CODE': 'PROJECT',
            // Задаем основные значения с настройками
            'LIST': {
                '10': { 'VALUE': 'Планирование', 'SORT': 10, 'DEF': 'Y' },
                '20': { 'VALUE': 'В разработке', 'SORT': 20, 'DEF': 'N' }
            },
            // Добавляем еще значения простой строкой
            'LIST_TEXT_VALUES': 'Тестирование\nЗавершен\nОтложен',
            'SETTINGS': {
                'SHOW_ADD_FORM': 'Y',
                'SHOW_EDIT_FORM': 'Y',
                'ADD_READ_ONLY_FIELD': 'N',
                'EDIT_READ_ONLY_FIELD': 'N',
                'SHOW_FIELD_PREVIEW': 'N'
            }
        }
    },
    function(result) {
        if (result.error()) {
            console.error(result.error());
        } else {
            console.log(result.data());
            // Итоговый список будет содержать 5 вариантов:
            // 1. Планирование (по умолчанию), 2. В разработке,
            // 3. Тестирование, 4. Завершен, 5. Отложен
        }
    }
);
```

### PHP CRest

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

$result = CRest::call(
    'lists.field.add',
    [
        'IBLOCK_TYPE_ID' => 'lists',
        'IBLOCK_ID' => '123',
        'FIELDS' => [
            'NAME' => 'Проект',
            'IS_REQUIRED' => 'Y',
            'MULTIPLE' => 'N',
            'TYPE' => 'L',
            'SORT' => '10',
            'CODE' => 'PROJECT',
            'LIST' => [
                '10' => ['VALUE' => 'Планирование', 'SORT' => 10, 'DEF' => 'Y'],
                '20' => ['VALUE' => 'В разработке', 'SORT' => 20, 'DEF' => 'N']
            ],
            'LIST_TEXT_VALUES' => 'Тестирование\nЗавершен\nОтложен',
            'SETTINGS' => [
                'SHOW_ADD_FORM' => 'Y',
                'SHOW_EDIT_FORM' => 'Y',
                'ADD_READ_ONLY_FIELD' => 'N',
                'EDIT_READ_ONLY_FIELD' => 'N',
                'SHOW_FIELD_PREVIEW' => 'N'
            ]
        ]
    ]
);

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

### Go

```go
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "lists.field.add", b24.Params{
	"IBLOCK_TYPE_ID": "lists",
	"IBLOCK_ID":      "123",
	"FIELDS": b24.Params{
		"NAME":        "Проект",
		"IS_REQUIRED": "Y",
		"MULTIPLE":    "N",
		"TYPE":        "L",
		"SORT":        "10",
		"CODE":        "PROJECT",
		"LIST": b24.Params{
			"10": b24.Params{
				"VALUE": "Планирование",
				"SORT":  10,
				"DEF":   "Y",
			},
			"20": b24.Params{
				"VALUE": "В разработке",
				"SORT":  20,
				"DEF":   "N",
			},
		},
		"LIST_TEXT_VALUES": "Тестирование\nЗавершен\nОтложен",
		"SETTINGS": b24.Params{
			"SHOW_ADD_FORM":        "Y",
			"SHOW_EDIT_FORM":       "Y",
			"ADD_READ_ONLY_FIELD":  "N",
			"EDIT_READ_ONLY_FIELD": "N",
			"SHOW_FIELD_PREVIEW":   "N",
		},
	},
})
if err != nil {
	return fmt.Errorf("lists.field.add: %w", err)
}

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

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