SmengoAPI

Сотрудники

Возвращает список сотрудников организации, с пагинацией и фильтром по отделу.

Скоуп

Требуется скоуп employees.read. Без него ключ получит 403 missing_scope. Какое право у создателя ключа нужно, чтобы выдать этот скоуп, — в Скоупах и правах → Таблица скоупов.

Query-параметры

Параметр Обязателен Описание
limit нет Целое 1..200, по умолчанию 100.
cursor нет Курсор meta.next_cursor предыдущего ответа — для следующей страницы.
department_id нет UUID отдела — строгое равенство. Неизвестный или чужой department_id — не ошибка, просто пустой список.

employee_id на этом ресурсе не поддержан: передача → 400 validation_error (параметр отклоняется явно, а не игнорируется молча — см. Конвенции → Фильтры). У сотрудников также нет from/to — это ресурс без временно́го измерения.

Запрос

curl -s https://smengo.com/api/v1/employees \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

С фильтром по отделу:

curl -s "https://smengo.com/api/v1/employees?department_id=9c1a2e34-5678-4abc-9def-0123456789ab" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Ответ

{
  "data": [
    {
      "id": "5e6d9f2a-3b7c-4e2f-9a1d-7c8e2f6b4a10",
      "full_name": "Иванова Мария",
      "position": "Бариста",
      "department_id": "9c1a2e34-5678-4abc-9def-0123456789ab",
      "employment_kind": "staff",
      "status": "active",
      "created_at": "2026-03-01T09:00:00.000Z",
      "updated_at": "2026-07-01T12:00:00.000Z"
    },
    {
      "id": "0b2f5e7a-9c31-4d6e-8a2b-4f1e6c9d3a52",
      "full_name": "Петров Игорь",
      "position": null,
      "department_id": null,
      "employment_kind": "trainee",
      "status": "access_revoked",
      "created_at": "2026-05-15T08:30:00.000Z",
      "updated_at": "2026-06-20T16:45:00.000Z"
    }
  ],
  "meta": { "next_cursor": null }
}

Поля ответа

Поле Тип Описание
id string (uuid) Уникальный идентификатор сотрудника.
full_name string Полное имя; список отсортирован по этому полю (плюс id как тай-брейкер).
position string | null Должность; может быть пустой.
department_id string (uuid) | null Отдел сотрудника (см. Отделы); может быть пустым, если сотрудник не привязан к отделу.
employment_kind "staff" | "trainee" Тип занятости: штатный сотрудник или стажёр.
status "active" | "access_revoked" Вычисляемый статус доступа: access_revoked, если у сотрудника отозван доступ, иначе active.
created_at string (ISO 8601 UTC) Время создания записи сотрудника.
updated_at string (ISO 8601 UTC) Время последнего изменения записи.

Уволенные сотрудники в ответе не появляются — они исключены из этого эндпоинта целиком, независимо от фильтров.

Пагинация

Список отсортирован по full_name, id. Если сотрудников больше, чем limit, meta.next_cursor содержит курсор для следующей страницы; передайте его в cursor следующего запроса как есть:

curl -s "https://smengo.com/api/v1/employees?limit=1&cursor=eyJrIjoi0JjQstCw0L3QvtCy0LAg0JzQsNGA0LjRjyIsImlkIjoiNWU2ZDlmMmEtM2I3Yy00ZTJmLTlhMWQtN2M4ZTJmNmI0YTEwIn0" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

meta.next_cursor равен null, когда сотрудников больше нет. Общие правила пагинации — в Конвенциях → Пагинация.

Что дальше

Была ли статья полезна?