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

Поля сотрудников

Создание, чтение, обновление и удаление пользовательских полей сотрудника — сущности users. Поле хранится под именем с префиксом UF_USR_ и под тем же именем приходит в карточке сотрудника.

Битрикс24 API: user.userfield.* Скоуп: user.userfield

Операции

Каталога типов у этой сущности нет: запрос 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" можно отправить обратно как есть — платформа понимает его как «включён», и цикл «прочитал → поменял одно свойство → отправил целиком» фильтр не гасит.

Типовой сценарий

  1. Посмотреть уже созданные поля: GET /v1/userfields/users.
  2. Создать поле с обязательными userTypeId и fieldName: POST /v1/userfields/users.
  3. Прочитать его описание — для enumeration с вариантами list: GET /v1/userfields/users/:id.
  4. Убедиться, что поле появилось в схеме сотрудника GET /v1/users/fields, и записать значение сотруднику: PATCH /v1/users/:id.
  5. Обновить (PATCH) или удалить (DELETE) поле по идентификатору.

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

Типы полей модуля обслуживают модули вроде crm и не предоставляют типы сотрудников.