SmengoAPI

Employees

Returns the organization's list of employees, with pagination and a department filter.

Scope

Requires the employees.read scope. Without it, the key gets 403 missing_scope. See Scopes and permissions → Scope table for which permission the key's creator needs to grant this scope.

Query parameters

Parameter Required Description
limit no Integer 1..200, defaults to 100.
cursor no The meta.next_cursor value from the previous response — for the next page.
department_id no A department UUID — exact match. An unknown or another organization's department_id is not an error, it just returns an empty list.

employee_id is not supported on this resource: passing it returns 400 validation_error (the parameter is explicitly rejected, not silently ignored — see Conventions → Filters). Employees also have no from/to — this resource has no time dimension.

Request

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

Filtered by department:

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

Response

{
  "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 }
}

Response fields

Field Type Description
id string (uuid) The employee's unique identifier.
full_name string Full name; the list is sorted by this field (plus id as a tiebreaker).
position string | null Job title; may be empty.
department_id string (uuid) | null The employee's department (see Departments); may be empty if the employee isn't assigned to a department.
employment_kind "staff" | "trainee" Employment type: staff or trainee.
status "active" | "access_revoked" A computed access status: access_revoked if the employee's access has been revoked, active otherwise.
created_at string (ISO 8601 UTC) When the employee record was created.
updated_at string (ISO 8601 UTC) When the record was last updated.

Terminated employees never appear in this response — they're excluded from this endpoint entirely, regardless of filters.

Pagination

The list is sorted by full_name, id. If there are more employees than limit, meta.next_cursor holds a cursor for the next page — pass it verbatim as cursor on the next request:

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

meta.next_cursor is null once there are no more employees. Full pagination rules are in Conventions → Pagination.

What's next

Was this article helpful?