Для 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 Код Описание
HTTP400 КодINVALID_ID Описание:id не является положительным целым числом — запрос отклонён до обращения к порталу
HTTP404 КодNOT_FOUND ОписаниеПоля с таким id нет
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа user.userfield
HTTP401 КодMISSING_API_KEY ОписаниеОтсутствует заголовок X-Api-Key
HTTP401 Код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, а не на единый набор.

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