#Создать сотрудника

POST /v1/users

Создаёт нового сотрудника на портале. Минимальное обязательное поле — email. Возвращает ID и полную запись только что созданного сотрудника.

Для интеграций с пользовательским вводом удобнее `POST /v1/users/invite`: он валидирует email на стороне Вайбкод (EMAIL_REQUIRED, EMAIL_INVALID) и автоматически проставляет departmentId: [1] для штатных сотрудников. Этот эндпоинт — низкоуровневая форма, ошибки прокидываются от Битрикс24 как есть.

#Поля запроса (body)

Параметр Тип Обяз. Описание
email string да Email — должен быть уникальным среди всех сотрудников портала
name string нет Имя
lastName string нет Фамилия
secondName string нет Отчество
workPosition string нет Должность
workPhone string нет Рабочий телефон
personalPhone string нет Личный телефон
personalMobile string нет Мобильный телефон
personalBirthday string нет Дата рождения (ISO 8601)
personalGender string нет Пол: M — мужской, F — женский
personalCity string нет Город
departmentId number[] условно Массив ID отделов. Для штатных сотрудников обязателен — без него Битрикс24 вернёт wrong_email. Для экстранета (EXTRANET: "Y") не используется
xmlId string нет Внешний идентификатор
EXTRANET string нет "Y" для пользователя экстранета. Тогда вместо departmentId нужен SONET_GROUP_ID (массив ID рабочих групп)
SONET_GROUP_ID number[] условно Массив ID рабочих групп — обязателен при EXTRANET: "Y". Список: `GET /v1/workgroups`

Полный список — Поля сотрудника. Пользовательские поля (UF_*) тоже принимаются.

#Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван",
    "lastName": "Петров",
    "email": "ivan.petrov@example.com",
    "workPosition": "Менеджер",
    "departmentId": [1]
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван",
    "lastName": "Петров",
    "email": "ivan.petrov@example.com",
    "workPosition": "Менеджер",
    "departmentId": [1]
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Иван',
    lastName: 'Петров',
    email: 'ivan.petrov@example.com',
    workPosition: 'Менеджер',
    departmentId: [1],
  }),
})

const { success, data } = await res.json()
console.log('User ID:', data.id)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Иван',
    lastName: 'Петров',
    email: 'ivan.petrov@example.com',
    workPosition: 'Менеджер',
    departmentId: [1],
  }),
})

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

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.id number ID созданного сотрудника

Ответ содержит полную запись со всеми полями сотрудника — формат тот же, что у `GET /v1/users/:id`.

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

JSON 
{
  "success": true,
  "data": {
    "id": 1331,
    "xmlId": "74668002",
    "active": true,
    "name": "Иван",
    "lastName": "Петров",
    "email": "ivan.petrov@example.com",
    "lastLogin": null,
    "dateRegister": "2026-05-06T00:00:00.000Z",
    "isOnline": false,
    "TIMESTAMP_X": {},
    "personalGender": null,
    "personalBirthday": null,
    "departmentId": [1],
    "workPosition": "Менеджер",
    "USER_TYPE": "employee"
  }
}

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

400 — email не передан или дублирует существующего сотрудника:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "wrong_email",
    "hint": "Bitrix24 `user.add` returns `wrong_email` for several distinct cases, not only malformed email: (a) the email is already used by ANOTHER Bitrix24 user globally — check with GET /v1/users?filter[EMAIL]=the-email first; (b) the email domain is not allowed by portal policy; (c) missing UF_DEPARTMENT for intranet users — try `departmentId: [1]`; (d) for external users pass `EXTRANET: \"Y\"` + `SONET_GROUP_ID: [groupId]`."
  }
}

#Ошибки

HTTP Код Описание
400 BITRIX_ERROR (wrong_email) Email не передан, дублирует существующего сотрудника, не прошёл политику домена портала, либо для штатного сотрудника не указан departmentId
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
403 SCOPE_DENIED API-ключ не имеет скоупа user

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

#Известные особенности

Email должен быть глобально уникальным. Битрикс24 проверяет уникальность среди всех сотрудников портала включая ранее деактивированных. Перед созданием — поиск через GET /v1/users?filter[EMAIL]=ivan.petrov@example.com. Если запись найдена и деактивирована, верните её в строй через PATCH /v1/users/:id { active: true } — это сохранит историю действий и связи сотрудника, в отличие от создания дубля.

Неоднозначность ошибки wrong_email. Битрикс24 возвращает wrong_email для нескольких разных ситуаций: email уже занят, домен запрещён политикой портала, у штатного сотрудника не указан departmentId, у внешнего — SONET_GROUP_ID. Сообщение не уточняет, какая именно. Чтобы разделить эти случаи на стороне Вайбкод, используйте `POST /v1/users/invite` — обёртка возвращает явные коды (EMAIL_REQUIRED, EMAIL_INVALID, SONET_GROUP_ID_REQUIRED) до запроса в Битрикс24.

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