docs

List employees (identity with pii:read only)

GET /employees

Scope employee:read PII identity

Requires the employee:read scope. Identity fields are present only for tokens that also hold pii:read. With pii:read, a page holds at most 100 rows (a larger limit is VALIDATION_FAILED), a name search (q) runs in cursor mode only (no offset, no total), and each page or search is audited and spends one unit of the token’s hourly personal-data budget per identity returned (at least one per search); a page that does not fit is RATE_LIMITED and spends nothing.

Example

curl "https://api.autociso.io/api/v1/employees" \
  -H "Authorization: Bearer <your-api-token>"

Response 200

{
  "data": [
    {
      "employmentType": "full_time",
      "hireDate": "2024-03-01T00:00:00Z",
      "id": "empl_1hgyun41rx48",
      "leaveDate": null,
      "managerId": "empl_1hgyq2b7z5tc",
      "status": "ACTIVE",
      "updatedAt": "2026-09-15T08:30:00Z"
    },
    {
      "employmentType": "contractor",
      "hireDate": "2025-06-02T00:00:00Z",
      "id": "empl_1hgyv08q3k2m",
      "leaveDate": "2026-08-31T00:00:00Z",
      "managerId": "empl_1hgyq2b7z5tc",
      "status": "TERMINATED",
      "updatedAt": "2026-09-01T07:10:00Z"
    }
  ],
  "error": null,
  "meta": {
    "limit": 25,
    "offset": 0,
    "total": 58
  }
}

Query parameters

  • limit integer
    Page size. minimum 1, maximum 100, default 25
  • offset integer
    Rows to skip (offset mode). Cannot be combined with cursor. minimum 0, maximum 10000, default 0
  • cursor string
    An opaque cursor taken from meta.nextCursor of the previous page (cursor mode). Valid for 24 hours and bound to the token and the query; do not parse or construct it.
  • sort[id] string
    Sort direction for id.
    "asc" | "desc"
  • sort[updatedAt] string
    Sort direction for updatedAt.
    "asc" | "desc"
  • filter[employmentType][eq] string
    Filter employmentType (eq).
    10 values
    "consultant" | "contractor" | "employee" | "freelance" | "full_time" | "intern" | "part_time" | "seasonal" | "temporary" | "vendor"
  • filter[employmentType][in] string
    Filter employmentType (in). Comma-separated, at most 50 values.
  • filter[id][eq] string
    Filter id (eq).
  • filter[id][in] string
    Filter id (in). Comma-separated, at most 50 values.
  • filter[managerId][eq] string
    Filter managerId (eq).
  • filter[managerId][in] string
    Filter managerId (in). Comma-separated, at most 50 values.
  • filter[status][eq] string
    Filter status (eq).
    "ACTIVE" | "ONBOARDING" | "TERMINATED"
  • filter[status][in] string
    Filter status (in). Comma-separated, at most 50 values.
  • filter[updatedAt][gte] string (date-time)
    Filter updatedAt (gte).
  • filter[updatedAt][lt] string (date-time)
    Filter updatedAt (lt).

Returns

The data field of the standard { data, error, meta } envelope:

An array of object:

  • email string
    Work e-mail. Every disclosure is audited (api.pii_read) and counts against the per-token PII window. Personal data: present only with pii:read.
  • employmentType string or null required
    Employment type, one of full_time, part_time, contractor, intern, temporary, employee, consultant, freelance, vendor, seasonal; null when unset or when the directory value is not one of these.
  • hireDate string (date-time) or null required
    Start date, when known.
  • id string required
    Employee id (empl_ FlakeID); the keyset tie-break.
  • leaveDate string (date-time) or null required
    End date, when known.
  • managerId string or null required
    Manager (empl_ FlakeID), when set.
  • name string
    Full name. Every disclosure is audited (api.pii_read) and counts against the per-token PII window. Personal data: present only with pii:read.
  • status string required
    ACTIVE, ONBOARDING or TERMINATED (empty for legacy rows).
  • updatedAt string (date-time) or null required
    Last write to the row (incremental-sync field); null until the row is backfilled.
  • No other fields.

Errors

Status Code Retry Meaning
400 - no The request is invalid.
401 - no The token is missing, malformed, expired or revoked.
402 - no The organisation’s plan does not include the feature this route needs.
403 - no The token may not use this route.
429 - yes Rate limit or row budget exceeded; retry after the time in Retry-After.
500 - no Unexpected server error.
503 - yes A dependency is temporarily unavailable; retry later.
Last reviewed: 2026-10-13

Was this page helpful?

Esc