Для AI-агентов: markdown этой страницы — /docs-content/userfields/users.md индекс документации — /llms.txt
Поля сотрудников
Создание, чтение, обновление и удаление пользовательских полей сотрудника — сущности users. Поле хранится под именем с префиксом UF_USR_ и под тем же именем приходит в карточке сотрудника.
Битрикс24 API: user.userfield.*
Скоуп: user.userfield
Операции
- Список полей сотрудников —
GET /v1/userfields/users - Получить поле сотрудника —
GET /v1/userfields/users/:id - Создать поле сотрудника —
POST /v1/userfields/users - Обновить поле сотрудника —
PATCH /v1/userfields/users/:id - Удалить поле сотрудника —
DELETE /v1/userfields/users/:id
Каталога типов у этой сущности нет: запрос GET /v1/userfields/users/types отвечает 400 UNSUPPORTED_ACTION. Тип поля задаётся при создании явно — допустимые значения userTypeId перечислены в разделе «Типы полей» ниже.
Скоуп ключа
Все пять операций требуют у API-ключа скоуп user.userfield — это отдельное право, его отмечают при выпуске ключа. Скоупа user для этих операций недостаточно: запрос без user.userfield отвечает 403 SCOPE_DENIED.
Имя поля
fieldName при создании обязателен. Имя хранится в верхнем регистре с префиксом UF_USR_: переданное UF_USR_BADGE_NO сохраняется как есть, badge_no становится UF_USR_BADGE_NO — регистр и префикс дополняет Битрикс24.
Под этим же именем поле стоит в схеме сотрудника GET /v1/users/fields и принимается в запросах к сотрудникам — POST /v1/users, PATCH /v1/users/:id. В отличие от полей CRM, у полей сотрудника имя определения и рабочее имя совпадают. Формат значения по типам — Пользовательские поля (UF).
Подписи поля
Подписи — label, editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage — принимаются при создании и обновлении, но в ответах этого раздела не возвращаются: ни список, ни карточка поля их не содержат. Проверить подпись можно в схеме сотрудника — GET /v1/users/fields отдаёт её в поле label.
Строка label без явных editFormLabel, listColumnLabel и listFilterLabel подставляется во все три подписи. Чтобы задать разные подписи по языкам портала, передайте объект: "editFormLabel": { "ru": "Табельный номер", "en": "Badge number" }.
Какие свойства применяются
Битрикс24 принимает тело запроса целиком и отвечает успехом, но часть свойств поля сотрудника не применяет — поле читается с прежними значениями. Проверено живыми вызовами на создании и обновлении.
| Свойство | Создание | Обновление |
|---|---|---|
Свойствоsort, xmlId, settings |
Созданиеприменяется | Обновлениеприменяется |
| Свойствоподписи | Созданиепринимаются — в ответах раздела их не видно, проверить можно по label в схеме сотрудника |
Обновлениепринимаются |
СвойствоshowFilter |
Созданиеприменяется | Обновлениеприменяется |
Свойствоlist — варианты поля enumeration |
Созданиеприменяется | Обновлениеприменяется |
Свойствоmultiple |
Созданиеприменяется | Обновлениене применяется — множественность задаётся один раз при создании |
Свойствоmandatory, isSearchable, showInList, editInList |
Созданиене применяется | Обновлениене применяется |
Поле сотрудника всегда читается с mandatory: "N", isSearchable: "N", showInList: "Y", editInList: "Y" — какие бы значения ни были переданы.
Типы полей
Допустимые значения userTypeId — каждое проверено созданием поля:
string, integer, double, boolean, date, datetime, enumeration, money, url, address, file, employee, crm, crm_status, iblock_section, iblock_element.
Значение вне этого списка отвечает 422 BITRIX_ERROR. Состав объекта settings зависит от типа — наборы ключей для основных типов приведены на странице Получить поле сотрудника.
Соответствие имён полей
В теле запроса и в ответе свойства поля называются camelCase-именами, а Битрикс24 хранит их в UPPER_CASE. Таблица помогает читать вложенные структуры — settings и элементы массива list, которые Битрикс24 возвращает «как есть».
| API (camelCase) | Битрикс24 (UPPER_CASE) |
|---|---|
API (camelCase)id |
Битрикс24 (UPPER_CASE)ID |
API (camelCase)entityId |
Битрикс24 (UPPER_CASE)ENTITY_ID |
API (camelCase)fieldName |
Битрикс24 (UPPER_CASE)FIELD_NAME |
API (camelCase)userTypeId |
Битрикс24 (UPPER_CASE)USER_TYPE_ID |
API (camelCase)xmlId |
Битрикс24 (UPPER_CASE)XML_ID |
API (camelCase)sort |
Битрикс24 (UPPER_CASE)SORT |
API (camelCase)multiple |
Битрикс24 (UPPER_CASE)MULTIPLE |
API (camelCase)mandatory |
Битрикс24 (UPPER_CASE)MANDATORY |
API (camelCase)showFilter |
Битрикс24 (UPPER_CASE)SHOW_FILTER |
API (camelCase)showInList |
Битрикс24 (UPPER_CASE)SHOW_IN_LIST |
API (camelCase)editInList |
Битрикс24 (UPPER_CASE)EDIT_IN_LIST |
API (camelCase)isSearchable |
Битрикс24 (UPPER_CASE)IS_SEARCHABLE |
API (camelCase)label |
Битрикс24 (UPPER_CASE)LABEL |
API (camelCase)editFormLabel |
Битрикс24 (UPPER_CASE)EDIT_FORM_LABEL |
API (camelCase)listColumnLabel |
Битрикс24 (UPPER_CASE)LIST_COLUMN_LABEL |
API (camelCase)listFilterLabel |
Битрикс24 (UPPER_CASE)LIST_FILTER_LABEL |
API (camelCase)errorMessage |
Битрикс24 (UPPER_CASE)ERROR_MESSAGE |
API (camelCase)helpMessage |
Битрикс24 (UPPER_CASE)HELP_MESSAGE |
API (camelCase)settings |
Битрикс24 (UPPER_CASE)SETTINGS |
API (camelCase)list |
Битрикс24 (UPPER_CASE)LIST |
Флаги «да/нет»
Свойства multiple и showFilter присылайте булевыми (true / false) либо строками "Y" / "N" — платформа приводит обе формы. В ответе multiple читается как "Y" или "N", а включённый showFilter — как "E": это форма хранения Битрикс24. Прочитанное "E" можно отправить обратно как есть — платформа понимает его как «включён», и цикл «прочитал → поменял одно свойство → отправил целиком» фильтр не гасит.
Типовой сценарий
- Посмотреть уже созданные поля:
GET /v1/userfields/users. - Создать поле с обязательными
userTypeIdиfieldName:POST /v1/userfields/users. - Прочитать его описание — для
enumerationс вариантамиlist:GET /v1/userfields/users/:id. - Убедиться, что поле появилось в схеме сотрудника
GET /v1/users/fields, и записать значение сотруднику:PATCH /v1/users/:id. - Обновить (
PATCH) или удалить (DELETE) поле по идентификатору.
Смотрите также
Типы полей модуля обслуживают модули вроде crm и не предоставляют типы сотрудников.