## Создать сотрудника `POST /v1/users` Создаёт нового сотрудника на портале. Минимальное обязательное поле — `email`. Возвращает ID и полную запись только что созданного сотрудника. > Для интеграций с пользовательским вводом удобнее [`POST /v1/users/invite`](/docs/entities/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`](/docs/entities/workgroups) | Полный список — [Поля сотрудника](/docs/entities/users/fields). Пользовательские поля (`UF_*`) тоже принимаются. Фотографию можно передать сразу при создании — тем же массивом `[имя файла, base64]`, что и при обновлении: `"personalPhoto": ["avatar.png", "iVBORw0KGgo..."]`. Прочие формы поля отклоняются; разбор и причины — в разделе «Фотография профиля» на странице [Обновить сотрудника](/docs/entities/users/update). ## Примеры ### curl — личный ключ ```bash 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-приложение ```bash 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`](/docs/entities/users/get). URL карточки сотрудника в Битрикс24 строится из `id`: ``` https://.bitrix24.ru/company/personal/user// ``` `` — домен портала. Доступ ограничен правами сотрудника в Битрикс24. ## Пример ответа ```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, "timestampX": {}, "personalGender": null, "personalBirthday": null, "departmentId": [1], "workPosition": "Менеджер", "userType": "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 (some portals restrict external domains); (c) missing UF_DEPARTMENT for intranet users — it is required for intranet invites (try `UF_DEPARTMENT: [1]` for the root department); (d) for external users pass `EXTRANET: \"Y\"` + `SONET_GROUP_ID: [groupId]` instead of UF_DEPARTMENT. For a convenience wrapper, try POST /v1/users/invite which sets sensible defaults. If the email is valid and unused, ask the portal admin to check user-invite settings." } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `BITRIX_ERROR` (`wrong_email`) | Email не передан, дублирует существующего сотрудника, не прошёл политику домена портала, либо для штатного сотрудника не указан `departmentId` | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `user` | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **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`](/docs/entities/users/invite) — обёртка возвращает явные коды (`EMAIL_REQUIRED`, `EMAIL_INVALID`, `SONET_GROUP_ID_REQUIRED`) до запроса в Битрикс24. ## Смотрите также - [Пригласить сотрудника](/docs/entities/users/invite) - [Поля сотрудника](/docs/entities/users/fields) - [Список сотрудников](/docs/entities/users/list) - [Отделы](/docs/entities/departments) - [Лимиты и оптимизация](/docs/optimization)