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, коли співробітників більше немає. Загальні правила пагінації — у Конвенціях → Пагінація.

Що далі

Чи була стаття корисною?