Skip to main content
Upsert — это операция “создать или обновить”. Если пользователь с указанным логином (phone, email или domain — в этом порядке приоритета), Telegram ID (tgId) или внешним идентификатором (extId) уже существует — его данные будут обновлены. Если пользователя нет — он будет создан.

Заголовки запроса

string
required
API токен сервисного пользователя в формате Bearer. Получите токен в панели администратора школы. Формат: Bearer YOUR_TOKEN.
string
required
Уникальный идентификатор продавца в системе. Используется для разграничения доступа между разными продавцами.
string
required
Уникальный идентификатор школы в системе. Определяет контекст выполнения операции.
Требуется аутентификация и право SchoolManageUsers.

Параметры запроса

Для определения существующего пользователя — передайте хотя бы один из ниже перечисленных параметров, в противном случае пользователь будет создаваться при каждом запросе.
В случае если пользователь найден по указанным ниже полям — произойдет только его обновление. В случае создания — логин и пароль для входа отправятся новому пользователю автоматически.
Полями для входа (логином) являются только email, phone и domain. extId и tgId участвуют в поиске существующего пользователя, но авторизоваться по ним нельзя.
string
Email адрес пользователя. Должен быть валидным email форматом. При передаче пустой строки — преобразуется в null.
string
Номер телефона пользователя. Должен быть в международном формате (например, +9876543210). При передаче пустой строки — преобразуется в null.
string
Доменный логин пользователя. До 65 символов: латинские буквы, цифры, _ и точки — точка не может быть первой/последней и не может идти подряд (автоматически приводится к нижнему регистру). Должен быть уникальным в рамках школы. Если не передан при создании — генерируется автоматически в формате id12345. Используется для входа наряду с email и phone.
integer
Telegram ID пользователя. Целое число или null. Логином не является.
string
Внешний идентификатор пользователя из вашей системы (например, GUID из CRM/1С). Строка до 50 символов без / и пробелов или null. Логином не является — используется только для связи и поиска.

Дополнительные параметры

enum
Статус учётной записи: Active, OnLeave, Banned, Blocked или Terminated. OnLeave — информационный (доступ не блокирует, управляется модулем отсутствий); Banned, Blocked и Terminated закрывают доступ: вход запрещён, активные сессии завершаются, зачисления блокируются. Terminated управляется автоматически модулем трудоустройств; при снятии бана (BannedActive) фактический статус пересчитывается автоматически. Статус Deleted зарезервирован системой. Подробнее — в user/create и user/update.
Булево поле banned из запроса удалено — блокировка управляется только через status. В ответе поля banned и active по-прежнему присутствуют как производные от status.
Владелец школы защищён: если апсерт находит владельца, перевод его в блокирующий статус (Banned/Blocked/Terminated) запрещён — вернётся ошибка ForbiddenModifySchoolOwner.

Параметры профиля

object
Объект с данными профиля пользователя.
При создании пользователя автоматически создается связанный профиль с указанными данными. Если профиль не указан, создается пустой профиль, поля firstName и lastName будут заполнены пользователем при первом входе в аккаунт.

Дополнительные агрегаты (extra)

object
Контейнер связанных данных, применяемых вместе с апсертом. Сейчас содержит блок staff.employments — массив трудоустройств (от 1 до 10): департамент, должность, вид и тип занятости. Доступно только для корпоративных школ. Если апсерт приводит к созданию пользователя — блок обязателен (сотрудник не может существовать без трудоустройства). Для существующего пользователя трудоустройства применяются идемпотентно: повторная передача той же активной пары департамент + должность не создаёт дубль.Состав полей элемента employments — как в user/create: extId, positionId/positionExtId, departmentId/departmentExtId, kind, type, startAt, rate.
Данные, которых нет в этой схеме (город, произвольный статус из CRM и т.п.), передаются через кастомные поля.

Требования к правам доступа

Для создания или обновления пользователя требуется право на управление пользователями школы.
Сервисный пользователь должен быть аутентифицирован по токену и иметь соответствующие права доступа к указанной школе.
При установке блокирующего статуса (Banned/Blocked/Terminated) все активные сессии пользователя автоматически завершаются — это реализовано для обеспечения безопасности.

Обновлено: 2026-07-22 12:24 UTC