# List employees (identity with pii:read only)

Requires the `employee:read` scope.

`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.

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | no | Page size. minimum 1, maximum 100, default 25 |
| `offset` | integer | no | Rows to skip (offset mode). Cannot be combined with cursor. minimum 0, maximum 10000, default 0 |
| `cursor` | string | no | 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 | no | Sort direction for id. One of `asc`, `desc`. |
| `sort[updatedAt]` | string | no | Sort direction for updatedAt. One of `asc`, `desc`. |
| `filter[employmentType][eq]` | string | no | Filter employmentType (eq). One of `consultant`, `contractor`, `employee`, `freelance`, `full_time`, `intern`, `part_time`, `seasonal`, `temporary`, `vendor`. |
| `filter[employmentType][in]` | string | no | Filter employmentType (in). Comma-separated, at most 50 values. |
| `filter[id][eq]` | string | no | Filter id (eq). |
| `filter[id][in]` | string | no | Filter id (in). Comma-separated, at most 50 values. |
| `filter[managerId][eq]` | string | no | Filter managerId (eq). |
| `filter[managerId][in]` | string | no | Filter managerId (in). Comma-separated, at most 50 values. |
| `filter[status][eq]` | string | no | Filter status (eq). One of `ACTIVE`, `ONBOARDING`, `TERMINATED`. |
| `filter[status][in]` | string | no | Filter status (in). Comma-separated, at most 50 values. |
| `filter[updatedAt][gte]` | string (date-time) | no | Filter updatedAt (gte). |
| `filter[updatedAt][lt]` | string (date-time) | no | Filter updatedAt (lt). |

## Returns

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

An array of object:
- `email`: optional 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 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 Start date, when known.
- `id`: string Employee id (empl_ FlakeID); the keyset tie-break.
- `leaveDate`: string (date-time) or null End date, when known.
- `managerId`: string or null Manager (empl_ FlakeID), when set.
- `name`: optional 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 ACTIVE, ONBOARDING or TERMINATED (empty for legacy rows).
- `updatedAt`: string (date-time) or null 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. |

## Example

### curl

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

### Python

```python
import requests

response = requests.get(
    "https://api.autociso.io/api/v1/employees",
    headers={"Authorization": "Bearer <your-api-token>"},
)
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.autociso.io/api/v1/employees", {
  method: "GET",
  headers: { "Authorization": "Bearer <your-api-token>" },
});
console.log(await response.json());
```

## Response (200)

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