Для 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 — личный ключ
curl "https://vibecode.bitrix24.tech/v1/userfields/users/6007923" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl "https://vibecode.bitrix24.tech/v1/userfields/users/6007923" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
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-приложение
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.
Пример ответа
{
"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 — поле не существует:
{
"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_VALUEinteger—SIZE,MIN_VALUE,MAX_VALUE,DEFAULT_VALUEdouble—PRECISION,SIZE,MIN_VALUE,MAX_VALUE,DEFAULT_VALUEdate—DEFAULT_VALUEобъектом{ "TYPE": "NONE", "VALUE": "" }datetime—DEFAULT_VALUEтаким же объектом,USE_SECOND,USE_TIMEZONEboolean—DEFAULT_VALUE,DISPLAY,LABEL,LABEL_CHECKBOXenumeration—DISPLAY,LIST_HEIGHT,CAPTION_NO_VALUE,SHOW_NO_VALUEfile—SIZE,LIST_WIDTH,LIST_HEIGHT,MAX_SHOW_SIZE,MAX_ALLOWED_SIZE,EXTENSIONS,TARGET_BLANK,DEFAULT_VIEWemployee—DEFAULT_VALUEпустым массивомcrm— флаги привязкиLEAD,CONTACT,COMPANY,DEALсо значениями"Y"/"N"
Тип вложенного ключа DEFAULT_VALUE тоже зависит от userTypeId: пустая строка для string и money, null для integer и double, число 0 для boolean, объект для date и datetime, пустой массив для employee. Опирайтесь на конкретный userTypeId, а не на единый набор.