Для AI-агентов: markdown этой страницы — /docs-content/userfields/users/list.md индекс документации — /llms.txt

Список полей сотрудников

GET /v1/userfields/users

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

Параметры

Параметр Тип Обяз. Описание
userTypeId (query) string нет Фильтр по типу поля. Допустимые значения — Типы полей. Пример: ?userTypeId=enumeration
fieldName (query) string нет Фильтр по полному имени поля с префиксом UF_USR_. Имя без префикса ничего не находит — ответ приходит с пустым data. Пример: ?fieldName=UF_USR_BADGE_NO

Результат упорядочен по полю sort по возрастанию. Параметр сортировки не принимается.

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/userfields/users?userTypeId=enumeration" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/userfields/users?userTypeId=enumeration" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/userfields/users?userTypeId=enumeration',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data, meta } = await res.json()
console.log(`Полей-списков: ${meta.total}`)

JavaScript — OAuth-приложение

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/userfields/users?userTypeId=enumeration',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data, meta } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив полей сотрудника. Набор свойств элемента совпадает с карточкой поля: id, entityId, fieldName, userTypeId, xmlId, sort, флаги, settings, у поля enumeration — list с вариантами
meta.total number Общее количество полей, соответствующих фильтру

Пример ответа

JSON 
{
  "success": true,
  "data": [
    {
      "id": 4925,
      "entityId": "USER",
      "fieldName": "UF_USR_1685540881093",
      "userTypeId": "enumeration",
      "xmlId": null,
      "sort": "100",
      "multiple": "N",
      "mandatory": "N",
      "showFilter": "E",
      "showInList": "Y",
      "editInList": "Y",
      "isSearchable": "N",
      "settings": {
        "DISPLAY": "UI",
        "LIST_HEIGHT": 1,
        "CAPTION_NO_VALUE": "",
        "SHOW_NO_VALUE": "Y"
      },
      "list": [
        {
          "ID": "1669",
          "SORT": "0",
          "VALUE": "Первый",
          "DEF": "N",
          "XML_ID": "be318f13536d5268018638e2520a4684"
        },
        {
          "ID": "1671",
          "SORT": "100",
          "VALUE": "Второй",
          "DEF": "N",
          "XML_ID": "8b24b8eca61a98bf8e240a26f943d839"
        },
        {
          "ID": "1673",
          "SORT": "200",
          "VALUE": "Третий",
          "DEF": "N",
          "XML_ID": "b49345c332ddd62d584f8d0fb4aebcec"
        }
      ]
    },
    {
      "id": 6007923,
      "entityId": "USER",
      "fieldName": "UF_USR_SHIFT",
      "userTypeId": "enumeration",
      "xmlId": null,
      "sort": "200",
      "multiple": "N",
      "mandatory": "N",
      "showFilter": "E",
      "showInList": "Y",
      "editInList": "Y",
      "isSearchable": "N",
      "settings": {
        "DISPLAY": "LIST",
        "LIST_HEIGHT": 1,
        "CAPTION_NO_VALUE": "",
        "SHOW_NO_VALUE": "Y"
      },
      "list": [
        {
          "ID": "3967",
          "SORT": "10",
          "VALUE": "Утро",
          "DEF": "N",
          "XML_ID": "46e4bae66329c39fafcbaef4262d490b"
        },
        {
          "ID": "3969",
          "SORT": "20",
          "VALUE": "Вечер",
          "DEF": "N",
          "XML_ID": "3351c3d103ce376358db5c39019af5c4"
        },
        {
          "ID": "3971",
          "SORT": "30",
          "VALUE": "Ночь",
          "DEF": "N",
          "XML_ID": "160aa32209dc24bfb699010bf2df174a"
        }
      ]
    }
  ],
  "meta": {
    "total": 2
  }
}

Пример ответа при ошибке

403 — у ключа нет скоупа user.userfield:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'user.userfield' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа user.userfield — скоупа user недостаточно
401 MISSING_API_KEY Отсутствует заголовок X-Api-Key
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Подписи в списке отсутствуют. Элемент списка не содержит editFormLabel, listColumnLabel, listFilterLabel, errorMessage и helpMessage — и карточка поля их тоже не возвращает. Подпись поля читается из схемы сотрудника GET /v1/users/fields, поле label.

Пагинация отсутствует. Эндпоинт возвращает все поля сотрудника без разбивки на страницы. meta.total отражает итоговое число полей в ответе.

Включённый фильтр читается как "E". В примере выше showFilter возвращается значением "E", а не "Y" — это форма хранения Битрикс24. Выключенный фильтр приходит как "N".

Смотрите также