Employees

The people in the workspace. Sensitive fields — national ID, pay, bank accounts — need employees.sensitive:read and are OMITTED rather than nulled without it, so a missing key means "not permitted", never "no value".

List employees

GET/v1/employees

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
status	string (enum)	No	Only employees with this employment status. separated is the state every offboarded employee ends in.
department_id	string	No	Only employees in this department.
employee_code	string	No	Look up one employee by the code the workspace assigned.
include_deleted	boolean	No	Include soft-deleted employees, flagged deleted: true. Required for a client syncing on updated_since to observe removals.

Responses

Status	Meaning
200	A page of employees.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Create an employee

POST/v1/employees

Supports Idempotency-Key, which is strongly recommended: without it a timed-out retry creates a second employee. Portal access is never granted by this endpoint, so importing staff sends no email.

employee_code is not accepted — the workspace assigns it from its own numbering settings and returns it on the created record. Nor is status: every employee is created as new.

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The created employee.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	The employee code is already in use, or the idempotency key was reused with a different body.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve an employee

GET/v1/employees/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The employee.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such employee in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Update an employee

PATCH/v1/employees/{id}

Only the fields present in the body are changed.

status and employee_code are not accepted, and a body carrying either is refused with 400 validation_failed naming the field. The status changes in the app, through activation, offboarding and the profile Status menu, each of which does more than set the field.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The updated employee.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such employee in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Delete an employee

DELETE/v1/employees/{id}

A soft delete. Returns the record with deleted: true rather than an empty body, so a syncing client sees the state it should mirror.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The deleted employee.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such employee in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.