Создать поле универсального списка lists.field.add

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: lists

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

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

Список доступных типов полей для универсального списка можно узнать с помощью метода lists.field.type.get

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

IBLOCK_TYPE_ID*
string

Идентификатор типа инфоблока.

Стандартные типы:

  • lists — универсальные списки
  • bitrix_processes — процессы
  • lists_socnet — списки групп

В коробочной версии можно также указать идентификатор произвольного существующего типа инфоблоков. IBLOCK_ID или IBLOCK_CODE должен указывать на инфоблок этого типа. Доступ к операции определяется стандартными правами пользователя на инфоблок, раздел или элемент

Идентификатор можно получить с помощью метода lists.get.iblock.type.id

IBLOCK_ID*
integer

Идентификатор инфоблока.

Идентификатор можно получить с помощью метода lists.get

IBLOCK_CODE*
string

Cимвольный код инфоблока.

Код можно получить с помощью метода lists.get

Необходимо указать хотя бы один из параметров: IBLOCK_ID или IBLOCK_CODE

FIELDS*
array

Массив параметров.

Подробное описание

Параметр 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

Идентификатор связанного списка. Обязателен для типов Привязка к разделам, Привязка к элементам и Привязка к элементам в виде списка

Примеры кода

Как использовать примеры в документации

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 -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
// 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)
}
<!-- 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>
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}")
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.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. Отложен
        }
    }
);
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>';
// 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)

Обработка ответа

HTTP-статус: 200

{
    "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

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

Название
тип

Описание

error
string

Строковый код ошибки. Состоит из цифр, латинских букв и знака подчеркивания. Может прийти пустым — тогда причину показывает только error_description

error_description
string

Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Возможные коды ошибок

Код

Описание

Значение

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

Недостаточно прав для добавления поля

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение