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

GET /v1/users/fields

Возвращает полный список полей сущности «сотрудник», включая пользовательские (UF_*) поля портала.

Каждое поле описано ключами type и readonly. У полей схемы приходят также подпись label и описание description, а у пола (personalGender) и типа учётной записи (userType) — перечень допустимых значений enum, где у каждого значения английская подпись label и русская labelRu. У пола стоит дополнительно nullable: true: если сотрудник его не указал, в ответе приходит null — то же самое сообщает и схема OpenAPI, где тип поля объявлен как ["string", "null"].

Примеры

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

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

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

curl "https://vibecode.bitrix24.tech/v1/users/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/users/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)

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

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

const { success, data } = await res.json()

Поля ответа

Подписи полей label и description приходят на русском языке, а те, что платформа берёт напрямую с портала, — на языке портала. Заголовками запроса язык не переключается.

Поля рабочих сведений (WORK_*, часть PERSONAL_*) приходят под исходными именами Битрикс24 в UPPER_SNAKE_CASE — их подписи Битрикс24 отдаёт сам, локализованные под язык портала. Десяти из них подписи в Битрикс24 нет вовсе (WORK_FAX, WORK_PAGER, WORK_STREET, WORK_MAILBOX, WORK_STATE, WORK_ZIP, WORK_COUNTRY, WORK_PROFILE, WORK_LOGO, WORK_NOTES) — там вместо подписи приходило само имя поля, и теперь подпись с описанием подставляет Вайбкод. Если портал такое поле всё-таки подписал сам, его подпись сохраняется без изменений. Незаполненное поле рабочих сведений в ответе на чтение обычно отсутствует целиком — проверяйте наличие ключа, а не пустую строку.

Пользовательские поля (UF_*) также возвращаются в ответах и принимаются при создании или обновлении. У пользовательского поля типа «список» (enumeration) в ответе есть массив items с возможными значениями (ID, VALUE, DEF, XML_ID) — при условии, что у ключа выдан скоуп user.userfield; без него поле возвращается с подписью, но без items.

Поля ufDepartment не существует — отдел сотрудника лежит в departmentId, массиве идентификаторов подразделений. Исходное имя Битрикс24 UF_DEPARTMENT принимается в select как алиас и проецирует канонический departmentId. Незнакомое имя в select не отклоняется — ответ дополняется предупреждением UNKNOWN_SELECT_FIELD в meta.warnings.

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

{
  "success": true,
  "data": {
    "fields": {
      "name": {
        "type": "string",
        "readonly": false,
        "label": "Имя",
        "description": "Имя сотрудника."
      },
      "timestampX": {
        "type": "datetime",
        "readonly": true,
        "label": "Дата изменения",
        "description": "Метка времени последнего изменения записи сотрудника."
      },
      "personalGender": {
        "type": "string",
        "readonly": false,
        "nullable": true,
        "label": "Пол",
        "description": "Пол сотрудника. Если сотрудник его не указал, в ответе приходит null.",
        "enum": [
          { "value": "M", "label": "Male", "labelRu": "Мужской" },
          { "value": "F", "label": "Female", "labelRu": "Женский" }
        ]
      },
      "WORK_CITY": { "type": "string", "readonly": false, "label": "Город работы" },
      "WORK_FAX": {
        "type": "string",
        "readonly": false,
        "label": "Факс компании",
        "description": "Номер факса компании в рабочих сведениях сотрудника."
      },
      "UF_USR_STATUS": {
        "type": "enumeration",
        "readonly": false,
        "label": "Статус",
        "items": [
          { "ID": "1", "VALUE": "Новый", "DEF": "N", "XML_ID": "x1" },
          { "ID": "2", "VALUE": "В работе", "DEF": "Y", "XML_ID": "x2" }
        ]
      }
    },
    "batch": ["create", "update", "delete"]
  }
}

Показано по одному полю каждого вида. Реальный ответ содержит 30+ полей схемы в camelCase — каждое с подписью и описанием, — поля рабочих сведений Битрикс24 в UPPER_SNAKE_CASE (WORK_*, часть PERSONAL_*) и UF-поля конкретного портала. Исходное имя Битрикс24 у поля схемы в ответе не дублируется: UF_DEPARTMENT приходит как departmentId, NAME — как name.

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

403 — нет скоупа:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'user' scope"
  }
}

Ошибки

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

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

• Создать сотрудника
• Обновить сотрудника
• Список сотрудников
• Пользовательские поля
• Лимиты и оптимизация