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

Получить поле сотрудника

GET /v1/userfields/users/:id

Возвращает описание одного пользовательского поля сотрудника по числовому идентификатору.

Параметры

Параметр Тип Обяз. Описание
:id (path) number да Числовой идентификатор поля (из ответа GET /v1/userfields/users или POST /v1/userfields/users). Ведущие нули игнорируются — 007 читается как 7

Примеры

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

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

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/userfields/users/6007923" \
  -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/6007923',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data } = await res.json()
console.log(data.fieldName, data.userTypeId)

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

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Объект поля
data.id number Числовой идентификатор поля
data.entityId string Внутренний идентификатор сущности — всегда USER
data.fieldName string Системное имя поля в формате UF_USR_*. Под этим же именем поле стоит в схеме сотрудника GET /v1/users/fields
data.userTypeId string Тип поля. Допустимые значения — Типы полей
data.xmlId string|null Внешний идентификатор для интеграций. Задаётся вручную при создании или обновлении
data.sort string Порядок сортировки в интерфейсе Битрикс24
data.multiple string Множественное поле: "Y" или "N"
data.mandatory string Обязательное при заполнении. У полей сотрудника всегда "N" — Какие свойства применяются
data.showFilter string Показывать в фильтре. "N" — выключен, включённый возвращается как "E" — форма хранения Битрикс24. Прочитанные "N" и "E" можно отправить обратно как есть
data.showInList string Показывать в списке сотрудников. У полей сотрудника всегда "Y"
data.editInList string Разрешить редактирование из списка. У полей сотрудника всегда "Y"
data.isSearchable string Участие в полнотекстовом поиске. У полей сотрудника всегда "N"
data.settings object Настройки поля, специфичные для userTypeId. Для enumeration — DISPLAY, LIST_HEIGHT, CAPTION_NO_VALUE, SHOW_NO_VALUE. Наборы для других типов — в «Известных особенностях»
data.list array Варианты поля типа enumeration. Для остальных типов поле отсутствует. Каждый элемент содержит ID, SORT, VALUE, DEF и XML_ID — все значения строки, XML_ID Битрикс24 генерирует сам, если не передан

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

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

JSON 
{
  "success": true,
  "data": {
    "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"
      }
    ]
  }
}

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

404 — поле не существует:

JSON 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "User field 999999999 not found"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_ID :id не является положительным целым числом — запрос отклонён до обращения к порталу
404 NOT_FOUND Поля с таким id нет
403 SCOPE_DENIED API-ключ не имеет скоупа user.userfield
401 MISSING_API_KEY Отсутствует заголовок X-Api-Key
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Карточка собирается из списка. Ответ — элемент списка полей, отобранный по id: набор свойств тот же, что у элемента списка, дополнительных данных карточка не несёт. Поэтому, если нужны несколько полей сразу, дешевле один запрос списка, чем карточка на каждое поле.

Поле settings. Структура объекта settings зависит от значения userTypeId. Наборы ключей, снятые с живых полей:

  • string — SIZE, ROWS, REGEXP, MIN_LENGTH, MAX_LENGTH, DEFAULT_VALUE
  • integer — SIZE, MIN_VALUE, MAX_VALUE, DEFAULT_VALUE
  • double — PRECISION, SIZE, MIN_VALUE, MAX_VALUE, DEFAULT_VALUE
  • date — DEFAULT_VALUE объектом { "TYPE": "NONE", "VALUE": "" }
  • datetime — DEFAULT_VALUE таким же объектом, USE_SECOND, USE_TIMEZONE
  • boolean — DEFAULT_VALUE, DISPLAY, LABEL, LABEL_CHECKBOX
  • enumeration — DISPLAY, LIST_HEIGHT, CAPTION_NO_VALUE, SHOW_NO_VALUE
  • file — SIZE, LIST_WIDTH, LIST_HEIGHT, MAX_SHOW_SIZE, MAX_ALLOWED_SIZE, EXTENSIONS, TARGET_BLANK, DEFAULT_VIEW
  • employee — DEFAULT_VALUE пустым массивом
  • crm — флаги привязки LEAD, CONTACT, COMPANY, DEAL со значениями "Y" / "N"

Тип вложенного ключа DEFAULT_VALUE тоже зависит от userTypeId: пустая строка для string и money, null для integer и double, число 0 для boolean, объект для date и datetime, пустой массив для employee. Опирайтесь на конкретный userTypeId, а не на единый набор.

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