Employees
Employees endpoints: parameters, fields and example responses.
Developer documentation
Lists employees
GET /api/v1/employees
Scope: employees:read
Employees inside the key's scope. A list item carries no national ID, IBAN, salary or personal details; those are only in the single-record read. The order is by ID and stable; no total count is returned. Sample records are not listed.
Parameters
| Field | Type | Description |
|---|---|---|
company_ (query) | string (uuid) | Only employees of this company. |
status (query) | string | Only employees in this status. Values: active, pre_start, inactive, terminated |
updated_ (query) | string (date-time) | Only records whose updated_at is greater than or equal to this moment (ISO 8601 with a time zone). Inclusive: send the last updated_at you saw and deduplicate by ID. |
cursor (query) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | ID of the employee record. |
company_ | string (uuid)required | The employee's company. |
org_ | string (uuid)requirednullable | The employee's unit; null when there is none. |
job_ | string (uuid)requirednullable | Job title; null when there is none. |
position_ | string (uuid)requirednullable | Position; null when there is none. |
manager_ | string (uuid)requirednullable | Employee ID of the manager. Null when the manager is a record the key cannot see. |
first_ | stringrequired | |
last_ | stringrequired | |
work_ | stringrequirednullable | Work email; null when there is none. |
status | stringrequired | active: employed; pre_start: hired, first day not reached; inactive: inactive; terminated: left. Values: active, pre_start, inactive, terminated |
employment_ | stringrequirednullable | Values: full_time, part_time, temporary, intern |
hire_ | string (date)requirednullable | Hire date. |
service_ | string (date)requirednullable | |
sgk_ | string (date)requirednullable | |
probation_ | string (date)requirednullable | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the employee record's own fields last changed (UTC). Changes to the national ID, IBAN, salary and personal details do not change this value. |
Example response
{
"data": [
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "[email protected]",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}
],
"next_cursor": null
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Creates an employee
POST /api/v1/employees
Scope: employees:write
Goes through the same rules as "Add employee" in the product. The body accepts only the fields below; an unknown field is 400. The national ID, IBAN and salary cannot be written through this endpoint. The response is the current state of the resource, so the key must also carry the employees:read scope. A company, unit, title, position or manager that is out of scope or does not exist gets the same 404 response.
Parameters
| Field | Type | Description |
|---|---|---|
Idempotency-Key (header) | stringrequired | Unique key of the request (a UUID is recommended). A repeated request with the same key and body returns the current state of the resource and Idempotent-Replayed: true; the window is 24 hours. |
Request body
| Field | Type | Description |
|---|---|---|
company_ | string (uuid)required | The employee's company. Must be inside the key's create scope. |
first_ | stringrequired | First name (1-100 characters). |
last_ | stringrequired | Last name (1-100 characters). |
work_ | string (email)nullable | Work email; unique among active employees (a clash is 409). |
org_ | string (uuid)nullable | Unit; must be a unit of the company. |
job_ | string (uuid)nullable | Job title. |
manager_ | string (uuid)nullable | Employee ID of the manager; must be inside the key's scope. Later it changes only through the approval flow in the product. |
status | string | active (default) or pre_start. pre_start requires hire_date, which must be after today. Values: active, pre_start |
position_ | string (uuid)nullable | Position; must be a position of the company. |
hire_ | string (date)nullable | Hire date (YYYY-MM-DD). |
service_ | string (date)nullable | |
sgk_ | string (date)nullable | |
employment_ | stringnullable | Employment type. Values: full_time, part_time, temporary, intern |
probation_ | string (date)nullable |
Responses
201 Created
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | ID of the employee record. |
company_ | string (uuid)required | The employee's company. |
org_ | string (uuid)requirednullable | The employee's unit; null when there is none. |
job_ | string (uuid)requirednullable | Job title; null when there is none. |
position_ | string (uuid)requirednullable | Position; null when there is none. |
manager_ | string (uuid)requirednullable | Employee ID of the manager. Null when the manager is a record the key cannot see. |
first_ | stringrequired | |
last_ | stringrequired | |
work_ | stringrequirednullable | Work email; null when there is none. |
status | stringrequired | active: employed; pre_start: hired, first day not reached; inactive: inactive; terminated: left. Values: active, pre_start, inactive, terminated |
employment_ | stringrequirednullable | Values: full_time, part_time, temporary, intern |
hire_ | string (date)requirednullable | Hire date. |
service_ | string (date)requirednullable | |
sgk_ | string (date)requirednullable | |
probation_ | string (date)requirednullable | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the employee record's own fields last changed (UTC). Changes to the national ID, IBAN, salary and personal details do not change this value. |
national_ | stringnullable | National ID number. Present only when the key has the field:national_id scope and its role has the same field class; an access record is written when a value is returned. |
iban | stringnullable | IBAN of the salary account. Present only with the field:iban scope and the same field class on the role; an access record is written when a value is returned. |
salary | objectnullable | The salary record in effect today (amount as a decimal string, currency, effective date); a future-dated salary is not returned. Present only with the field:salary scope and the same field class on the role; an access record is written when a value is returned. |
personal | object | Personal details (birth date, gender, phone, personal email, address, city). Present only with the field:pii scope and the same field class on the role; an access record is written when a value is returned. |
Example response
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "[email protected]",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found409:idempotency_in_progress,conflict413:payload_too_large415:unsupported_media_type422:idempotency_key_reused429:rate_limited500:internal_error503:timeout
Returns one employee
GET /api/v1/employees/{id}
Scope: employees:read
The national ID, IBAN, salary and personal details are present only when the matching field: scope and the same field class on the role are both there; otherwise the field name itself is absent. A record the key cannot see and a record that does not exist get the same 404 response.
Parameters
| Field | Type | Description |
|---|---|---|
id (path) | string (uuid)required | ID of the employee record. |
Responses
200 Successful
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | ID of the employee record. |
company_ | string (uuid)required | The employee's company. |
org_ | string (uuid)requirednullable | The employee's unit; null when there is none. |
job_ | string (uuid)requirednullable | Job title; null when there is none. |
position_ | string (uuid)requirednullable | Position; null when there is none. |
manager_ | string (uuid)requirednullable | Employee ID of the manager. Null when the manager is a record the key cannot see. |
first_ | stringrequired | |
last_ | stringrequired | |
work_ | stringrequirednullable | Work email; null when there is none. |
status | stringrequired | active: employed; pre_start: hired, first day not reached; inactive: inactive; terminated: left. Values: active, pre_start, inactive, terminated |
employment_ | stringrequirednullable | Values: full_time, part_time, temporary, intern |
hire_ | string (date)requirednullable | Hire date. |
service_ | string (date)requirednullable | |
sgk_ | string (date)requirednullable | |
probation_ | string (date)requirednullable | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the employee record's own fields last changed (UTC). Changes to the national ID, IBAN, salary and personal details do not change this value. |
national_ | stringnullable | National ID number. Present only when the key has the field:national_id scope and its role has the same field class; an access record is written when a value is returned. |
iban | stringnullable | IBAN of the salary account. Present only with the field:iban scope and the same field class on the role; an access record is written when a value is returned. |
salary | objectnullable | The salary record in effect today (amount as a decimal string, currency, effective date); a future-dated salary is not returned. Present only with the field:salary scope and the same field class on the role; an access record is written when a value is returned. |
personal | object | Personal details (birth date, gender, phone, personal email, address, city). Present only with the field:pii scope and the same field class on the role; an access record is written when a value is returned. |
Example response
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "[email protected]",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Updates the allowed fields of an employee
PATCH /api/v1/employees/{id}
Scope: employees:write
Partial update: a field that is not sent does not change, the body carries at least one field, an unknown field is 400. The manager, status, company, national ID, IBAN and salary do not change through this endpoint. Values are absolute: repeating the same request leaves the record in the same state, no Idempotency-Key is needed. The response is the current state of the resource, so the key must also carry the employees:read scope. A record the key cannot see and a record that does not exist get the same 404 response. There is no precondition: the last write wins (of two concurrent updates the later one stands). First and last name belong to the person: they also change on that person's employment record in another company, when there is one.
Parameters
| Field | Type | Description |
|---|---|---|
id (path) | string (uuid)required | ID of the employee record. |
Request body
| Field | Type | Description |
|---|---|---|
first_ | string | First name (1-100 characters). |
last_ | string | Last name (1-100 characters). |
work_ | string (email)nullable | Work email; unique among active employees (a clash is 409). |
org_ | string (uuid)nullable | Unit; must be a unit of the company. |
job_ | string (uuid)nullable | Job title. |
position_ | string (uuid)nullable | Position; must be a position of the company. |
hire_ | string (date)nullable | Hire date (YYYY-MM-DD). |
service_ | string (date)nullable | |
sgk_ | string (date)nullable | |
employment_ | stringnullable | Employment type. Values: full_time, part_time, temporary, intern |
probation_ | string (date)nullable | |
effective_ | string (date) | The day a unit, position or title change takes effect; today when omitted. |
Responses
200 Successful
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | ID of the employee record. |
company_ | string (uuid)required | The employee's company. |
org_ | string (uuid)requirednullable | The employee's unit; null when there is none. |
job_ | string (uuid)requirednullable | Job title; null when there is none. |
position_ | string (uuid)requirednullable | Position; null when there is none. |
manager_ | string (uuid)requirednullable | Employee ID of the manager. Null when the manager is a record the key cannot see. |
first_ | stringrequired | |
last_ | stringrequired | |
work_ | stringrequirednullable | Work email; null when there is none. |
status | stringrequired | active: employed; pre_start: hired, first day not reached; inactive: inactive; terminated: left. Values: active, pre_start, inactive, terminated |
employment_ | stringrequirednullable | Values: full_time, part_time, temporary, intern |
hire_ | string (date)requirednullable | Hire date. |
service_ | string (date)requirednullable | |
sgk_ | string (date)requirednullable | |
probation_ | string (date)requirednullable | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the employee record's own fields last changed (UTC). Changes to the national ID, IBAN, salary and personal details do not change this value. |
national_ | stringnullable | National ID number. Present only when the key has the field:national_id scope and its role has the same field class; an access record is written when a value is returned. |
iban | stringnullable | IBAN of the salary account. Present only with the field:iban scope and the same field class on the role; an access record is written when a value is returned. |
salary | objectnullable | The salary record in effect today (amount as a decimal string, currency, effective date); a future-dated salary is not returned. Present only with the field:salary scope and the same field class on the role; an access record is written when a value is returned. |
personal | object | Personal details (birth date, gender, phone, personal email, address, city). Present only with the field:pii scope and the same field class on the role; an access record is written when a value is returned. |
Example response
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "[email protected]",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found409:idempotency_in_progress,conflict413:payload_too_large415:unsupported_media_type429:rate_limited500:internal_error503:timeout