Skip to main content
GET
List Workforce Employees
← Own Workforce API Retrieve a paginated list of employee records. Each item is one person, flattened with the dates and category of the contract that represents them in the listing.

Request

Headers

string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

integer
default:"1"
Page number, starting at 1
integer
default:"50"
Page size, between 1 and 100
string
Search by the employee identifier your own HR system usesExample: external_employee_id=EMP-2024-001
array[string]
Filter by the source upload file. Repeat the parameter for several files.Pass the nil UUID 00000000-0000-0000-0000-000000000000 to match rows that came from no file — that is, rows with a null file_id.Example: file_id[]=9f1c7f2a-64a1-4b2c-9d3e-70a5b8c1d2e3
datetime
Only rows created at or after this instantFormat: ISO 8601 — 2026-01-01T00:00:00
datetime
Only rows created at or before this instantFormat: ISO 8601 — 2026-12-31T23:59:59
boolean
default:"false"
Group view. false returns the header organization only. true widens the list to the header organization’s accepted business family — itself plus its accepted, enabled descendants.
array[string]
Restrict a group-view list to these organizations, intersected with the family resolved above. Only meaningful together with consolidate_group=true.Example: organization_id[]=a8315ef3-dd50-43f8-b7ce-d839e68d51fa
string
Scope the list to a project’s reporting perimeter. Only applied together with scope_to_project_organizations=true.
boolean
default:"false"
When true, narrow the perimeter to the organizations attached to project_id instead of the whole group tree.

Response

array[object]
integer
Number of rows matching the filters, across all pages
integer
Current page
integer
Current page size
string | null
Fingerprint of the filters that produced this page. Pass it to Bulk Delete Workforce Employees by Filters to prove you are deleting exactly what you listed — if the filters changed in between, that call fails instead of deleting a wider set.
Every date field in this response is typed as a string, not a date, including contract_start_date and created_at. Parse accordingly.

Example

Successful Response

Common Errors

401 Unauthorized

Cause: the key is invalid, or it does not belong to the organization in x-organization-id — the two are looked up as a pair. A request carrying no credentials at all answers AUTH_REQUIRED instead.

403 Forbidden

Cause: the key’s owner is not an enabled member of the organization in x-organization-id.

400 Bad Request

Cause: x-organization-id absent while authenticating with an API key. It is the first error a new integration hits, and it is a 400 rather than a 422 because the header is read inside the auth dependency.

422 Unprocessable Entity

Cause: a malformed query parameter. Authentication is resolved first — the router-level dependency runs before the endpoint’s own parameters are validated — so a request that is both unauthenticated and malformed answers 401, not 422.

Get employee

A single employee by id

Unique values

Build the file filter for this list

Employees with contracts

Employees, contracts and remuneration periods in one call

Bulk delete by filters

Delete exactly what this list returned