Получить список пользовательских полей контактов crm.contact.userfield.list

Scope: crm

Кто может выполнять метод: администратор

Метод crm.contact.userfield.list возвращает список пользовательских полей контактов по фильтру.

Выводится и информация об этих полях, но без названия, которое присвоил полю пользователь, только внутренний идентификатор. Если нужно пользовательское название поля, воспользуйтесь методом crm.contact.list, который выводит как стандартные поля, так и пользовательские.

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

Название
тип

Описание

filter
object

Объект формата:

{
            field_1: value_1,
            field_2: value_2,
            ...,
            field_n: value_n,
        }

где:

field_n — название поля, по которому будет отфильтрована выборка пользовательских полей
value_n — значение фильтра (доступно лишь точное соответствие)

Все условия по отдельным полям соединяются с помощью AND. Смотрите ниже список доступных полей для фильтрации

order
object

Объект формата:

{
            field_1: value_1,
            field_2: value_2,
            ...,
            field_n: value_n,
        }

где:

field_n — название поля, по которому будет произведена сортировка выборки элементов
value_n — значение типа string, равное:
- ASC — сортировка по возрастанию
- DESC — сортировка по убыванию

Список доступных полей для сортировки:

ID — идентификатор пользовательского поля
FIELD_NAME — код пользовательского поля
USER_TYPE_ID — тип пользовательского поля
XML_ID — внешний код
SORT — индекс сортировки

По умолчанию:

{
            "SORT": "ASC",
            "ID": "ASC"
        }

Доступные для фильтрации поля

Название `тип`	Описание
ID `integer`	Идентификатор пользовательского поля
FIELD_NAME `string`	Код пользовательского поля
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 пользовательские типы полей
XML_ID `string`	Внешний код
SORT `integer`	Индекс сортировки
MULTIPLE `boolean`	Является ли пользовательское поле множественным (`Y` — да / `N` — нет)
MANDATORY `boolean`	Является ли пользовательское поле обязательным (`Y` — да/ `N` — нет)
SHOW_FILTER `char`	Показывать ли в фильтре списка. Возможные значения: `N` — не показывать `I` — точное совпадение `E` — маска `S` — подстрока
SHOW_IN_LIST `boolean`	Показывать ли в списке (`Y` — да/ `N` — нет). Данный параметр ни на что не влияет в рамках `crm`
EDIT_IN_LIST `boolean`	Разрешать ли редактирование пользователем (`Y` — да/ `N` — нет)
IS_SEARCHABLE `boolean`	Участвуют ли значения поля в поиске (`Y` — да/ `N` — нет) Данный параметр ни на что не влияет в рамках `crm`
LANG `string`	Языковой идентификатор. При фильтрации по данному параметру будет предоставлен набор полей со значениями на переданном языке: `EDIT_FORM_LABEL` — подпись в форме редактирования `LIST_COLUMN_LABEL` — заголовок в списке `LIST_FILTER_LABEL` — подпись фильтра в списке `ERROR_MESSAGE` — сообщение об ошибке `HELP_MESSAGE` — помощь

Примеры кода

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

Получить список пользовательских полей, которые:

являются множественными
являются обязательными
имеют подписи пользовательского поля на русском языке

Задать следующий порядок сортировки у данной выборки: тип поля и индекс сортировки по возрастанию.

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"filter":{"MULTIPLE":"Y","MANDATORY":"Y","LANG":"ru"},"order":{"USER_TYPE_ID":"ASC","SORT":"ASC"}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.contact.userfield.list

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"filter":{"MULTIPLE":"Y","MANDATORY":"Y","LANG":"ru"},"order":{"USER_TYPE_ID":"ASC","SORT":"ASC"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.contact.userfield.list

// callListMethod: Получает все данные сразу. Используйте только для небольших выборок (< 1000 элементов) из-за высокой нагрузки на память.
        
        try {
          const response = await $b24.callListMethod(
            'crm.contact.userfield.list',
            {
              filter: {
                MULTIPLE: "Y",
                MANDATORY: "Y",
                LANG: "ru",
              },
              order: {
                USER_TYPE_ID: "ASC",
                SORT: "ASC",
              },
            },
            (progress) => { 
              result.error()
                ? console.error(result.error())
                : console.info(result.data())
              ;
            }
          );
          const items = response.getData() || [];
          for (const entity of items) { console.log('Entity:', entity); }
        } catch (error) {
          console.error('Request failed', error);
        }
        
        // fetchListMethod: Выбирает данные по частям с помощью итератора. Используйте для больших объемов данных для эффективного потребления памяти.
        
        try {
          const generator = $b24.fetchListMethod('crm.contact.userfield.list', {
            filter: {
              MULTIPLE: "Y",
              MANDATORY: "Y",
              LANG: "ru",
            },
            order: {
              USER_TYPE_ID: "ASC",
              SORT: "ASC",
            },
          }, 'ID');
          for await (const page of generator) {
            for (const entity of page) { console.log('Entity:', entity); }
          }
        } catch (error) {
          console.error('Request failed', error);
        }
        
        // callMethod: Ручное управление постраничной навигацией через параметр start. Используйте для точного контроля над пакетами запросов. Для больших данных менее эффективен, чем fetchListMethod.
        
        try {
          const response = await $b24.callMethod('crm.contact.userfield.list', {
            filter: {
              MULTIPLE: "Y",
              MANDATORY: "Y",
              LANG: "ru",
            },
            order: {
              USER_TYPE_ID: "ASC",
              SORT: "ASC",
            },
          }, 0);
          const result = response.getData().result || [];
          for (const entity of result) { console.log('Entity:', entity); }
        } catch (error) {
          console.error('Request failed', error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.contact.userfield.list',
                    [
                        'filter' => [
                            'MULTIPLE' => 'Y',
                            'MANDATORY' => 'Y',
                            'LANG' => 'ru',
                        ],
                        'order' => [
                            'USER_TYPE_ID' => 'ASC',
                            'SORT' => 'ASC',
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            if ($result->error()) {
                error_log($result->error());
                echo 'Error: ' . $result->error();
            } else {
                echo 'Success: ' . print_r($result->data(), true);
            }
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error fetching user fields: ' . $e->getMessage();
        }

BX24.callMethod(
            'crm.contact.userfield.list',
            {
                filter: {
                    MULTIPLE: "Y",
                    MANDATORY: "Y",
                    LANG: "ru",
                },
                order: {
                    USER_TYPE_ID: "ASC",
                    SORT: "ASC",
                },
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data())
                ;
            },
        );

require_once('crest.php');
        
        $result = CRest::call(
            'crm.contact.userfield.list',
            [
                'filter' => [
                    'MULTIPLE' => "Y",
                    'MANDATORY' => "Y",
                    'LANG' => "ru",
                ],
                'order' => [
                    'USER_TYPE_ID' => "ASC",
                    'SORT' => "ASC",
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

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

HTTP-статус: 200

{
            "result": [
                {
                "ID": "474",
                "ENTITY_ID": "CRM_CONTACT",
                "FIELD_NAME": "UF_CRM_1724412832",
                "USER_TYPE_ID": "address",
                "XML_ID": null,
                "SORT": "300",
                "MULTIPLE": "Y",
                "MANDATORY": "Y",
                "SHOW_FILTER": "E",
                "SHOW_IN_LIST": "Y",
                "EDIT_IN_LIST": "Y",
                "IS_SEARCHABLE": "N",
                "SETTINGS": {
                    "SHOW_MAP": "Y"
                },
                "EDIT_FORM_LABEL": "Пользовательское поле (Адрес)",
                "LIST_COLUMN_LABEL": "Пользовательское поле (Адрес)",
                "LIST_FILTER_LABEL": "Пользовательское поле (Адрес)",
                "ERROR_MESSAGE": null,
                "HELP_MESSAGE": null
                },
                {
                "ID": "475",
                "ENTITY_ID": "CRM_CONTACT",
                "FIELD_NAME": "UF_CRM_1724412867",
                "USER_TYPE_ID": "crm",
                "XML_ID": null,
                "SORT": "1400",
                "MULTIPLE": "Y",
                "MANDATORY": "Y",
                "SHOW_FILTER": "I",
                "SHOW_IN_LIST": "Y",
                "EDIT_IN_LIST": "Y",
                "IS_SEARCHABLE": "N",
                "SETTINGS": {
                    "CONTACT": "Y",
                    "COMPANY": "Y",
                    "DYNAMIC_1224": "Y",
                    "DYNAMIC_1226": "Y",
                    "DYNAMIC_1268": "Y",
                    "DYNAMIC_1278": "Y",
                    "LEAD": null
                },
                "EDIT_FORM_LABEL": "Пользовательское поле (Привязка к элементам CRM))",
                "LIST_COLUMN_LABEL": "Пользовательское поле (Привязка к элементам CRM))",
                "LIST_FILTER_LABEL": "Пользовательское поле (Привязка к элементам CRM))",
                "ERROR_MESSAGE": null,
                "HELP_MESSAGE": null
                },
                {
                "ID": "472",
                "ENTITY_ID": "CRM_CONTACT",
                "FIELD_NAME": "UF_CRM_1724412764",
                "USER_TYPE_ID": "date",
                "XML_ID": null,
                "SORT": "2000",
                "MULTIPLE": "Y",
                "MANDATORY": "Y",
                "SHOW_FILTER": "E",
                "SHOW_IN_LIST": "Y",
                "EDIT_IN_LIST": "Y",
                "IS_SEARCHABLE": "N",
                "SETTINGS": {
                    "DEFAULT_VALUE": {
                    "VALUE": "2024-08-22",
                    "TYPE": "FIXED"
                    }
                },
                "EDIT_FORM_LABEL": "Пользовательское поле (Дата)",
                "LIST_COLUMN_LABEL": "Пользовательское поле (Дата)",
                "LIST_FILTER_LABEL": "Пользовательское поле (Дата)",
                "ERROR_MESSAGE": null,
                "HELP_MESSAGE": null
                },
                {
                "ID": "471",
                "ENTITY_ID": "CRM_CONTACT",
                "FIELD_NAME": "UF_CRM_1724412713",
                "USER_TYPE_ID": "double",
                "XML_ID": null,
                "SORT": "1500",
                "MULTIPLE": "Y",
                "MANDATORY": "Y",
                "SHOW_FILTER": "E",
                "SHOW_IN_LIST": "Y",
                "EDIT_IN_LIST": "Y",
                "IS_SEARCHABLE": "N",
                "SETTINGS": {
                    "PRECISION": 2,
                    "SIZE": 20,
                    "MIN_VALUE": 0,
                    "MAX_VALUE": 0,
                    "DEFAULT_VALUE": 150
                },
                "EDIT_FORM_LABEL": "Пользовательское поле (число)",
                "LIST_COLUMN_LABEL": "Пользовательское поле (число)",
                "LIST_FILTER_LABEL": "Пользовательское поле (число)",
                "ERROR_MESSAGE": null,
                "HELP_MESSAGE": null
                },
                {
                "ID": "473",
                "ENTITY_ID": "CRM_CONTACT",
                "FIELD_NAME": "UF_CRM_1724412805",
                "USER_TYPE_ID": "employee",
                "XML_ID": null,
                "SORT": "800",
                "MULTIPLE": "Y",
                "MANDATORY": "Y",
                "SHOW_FILTER": "I",
                "SHOW_IN_LIST": "Y",
                "EDIT_IN_LIST": "Y",
                "IS_SEARCHABLE": "N",
                "SETTINGS": [],
                "EDIT_FORM_LABEL": "Пользовательское поле (Сотрудник)",
                "LIST_COLUMN_LABEL": "Пользовательское поле (Сотрудник)",
                "LIST_FILTER_LABEL": "Пользовательское поле (Сотрудник)",
                "ERROR_MESSAGE": null,
                "HELP_MESSAGE": null
                },
                {
                "ID": "476",
                "ENTITY_ID": "CRM_CONTACT",
                "FIELD_NAME": "UF_CRM_1724412914",
                "USER_TYPE_ID": "file",
                "XML_ID": null,
                "SORT": "1200",
                "MULTIPLE": "Y",
                "MANDATORY": "Y",
                "SHOW_FILTER": "N",
                "SHOW_IN_LIST": "Y",
                "EDIT_IN_LIST": "Y",
                "IS_SEARCHABLE": "N",
                "SETTINGS": {
                    "SIZE": 20,
                    "LIST_WIDTH": 0,
                    "LIST_HEIGHT": 0,
                    "MAX_SHOW_SIZE": 0,
                    "MAX_ALLOWED_SIZE": 0,
                    "EXTENSIONS": [],
                    "TARGET_BLANK": "Y"
                },
                "EDIT_FORM_LABEL": "Пользовательское поле (Файл)",
                "LIST_COLUMN_LABEL": "Пользовательское поле (Файл)",
                "LIST_FILTER_LABEL": "Пользовательское поле (Файл)",
                "ERROR_MESSAGE": null,
                "HELP_MESSAGE": null
                }
            ],
            "total": 6,
            "time": {
                "start": 1724435524.016968,
                "finish": 1724435527.855702,
                "duration": 3.8387339115142822,
                "processing": 0.366832971572876,
                "date_start": "2024-08-23T19:52:04+02:00",
                "date_finish": "2024-08-23T19:52:07+02:00",
                "operating": 0
            }
        }

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

Название `тип`	Описание
result `userfield[]`	Корневой элемент ответа, содержит список пользовательских полей. Структура отдельно взятого пользовательского поля идентична `userfield` за исключением того, что поля: `EDIT_FORM_LABEL`, `LIST_COLUMN_LABEL`, `LIST_FILTER_LABEL`, `ERROR_MESSAGE`, `HELP_MESSAGE` отдаются либо в виде `string` при передаче `filter.LANG`, либо не отдаются вовсе
total `integer`	Количество найденных пользовательских полей
time `time`	Информация о времени выполнения запроса

Обработка ошибок

HTTP-статус: 400

{
            "error": "",
            "error_description": "Parameter 'filter' must be array."
        }

Название `тип`	Описание
error `string`	Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания
error_description `error_description`	Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

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

Код	Описание	Значение
`-`	`Parameter 'order' must be array`	Переданный `order` не является объектом
`-`	`Parameter 'filter' must be array`	Переданный `filter` не является объектом
`-`	`Access denied`	У пользователя нет административных прав

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

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус	Код Текст ошибки	Описание
`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	Превышен лимит на интенсивность запросов
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	Текущий метод не разрешен для вызова с помощью batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	Превышена максимальная длина параметров, переданных в метод batch
`401`	`NO_AUTH_FOUND` Wrong authorization data	Неверный access-токен или код вебхука
`400`	`INVALID_REQUEST` Https required	Для вызовов методов требуется использовать протокол HTTPS
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	REST API доступен только на коммерческих планах
`403`	`INVALID_CREDENTIALS` Invalid request credentials	У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	Манифест недоступен
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более высоких привилегий, чем предоставляет токен вебхука
`401`	`expired_token` The access token provided has expired	Предоставленный access-токен доступа истек
`403`	`user_access_error` The user does not have access to the application	Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям
`500`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Получить пользовательское поле контактов по Id

Удалить пользовательское поле контактов

Получить список пользовательских полей контактов crm.contact.userfield.list

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

Доступные для фильтрации поляДоступные для фильтрации поля

Примеры кодаПримеры кода

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

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

Обработка ошибокОбработка ошибок

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

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

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