Skip to content

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

employees.list: Parameters
FieldTypeDescription
company_id (query)string (uuid)Only employees of this company.
status (query)stringOnly employees in this status. Values: active, pre_start, inactive, terminated
updated_since (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)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

employees.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)requiredID of the employee record.
company_idstring (uuid)requiredThe employee's company.
org_unit_idstring (uuid)requirednullableThe employee's unit; null when there is none.
job_title_idstring (uuid)requirednullableJob title; null when there is none.
position_idstring (uuid)requirednullablePosition; null when there is none.
manager_idstring (uuid)requirednullableEmployee ID of the manager. Null when the manager is a record the key cannot see.
first_namestringrequired
last_namestringrequired
work_emailstringrequirednullableWork email; null when there is none.
statusstringrequiredactive: employed; pre_start: hired, first day not reached; inactive: inactive; terminated: left. Values: active, pre_start, inactive, terminated
employment_typestringrequirednullable Values: full_time, part_time, temporary, intern
hire_datestring (date)requirednullableHire date.
service_start_datestring (date)requirednullable
sgk_entry_datestring (date)requirednullable
probation_endstring (date)requirednullable
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

employees.create: Parameters
FieldTypeDescription
Idempotency-Key (header)stringrequiredUnique 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

employees.create: Request body
FieldTypeDescription
company_idstring (uuid)requiredThe employee's company. Must be inside the key's create scope.
first_namestringrequiredFirst name (1-100 characters).
last_namestringrequiredLast name (1-100 characters).
work_emailstring (email)nullableWork email; unique among active employees (a clash is 409).
org_unit_idstring (uuid)nullableUnit; must be a unit of the company.
job_title_idstring (uuid)nullableJob title.
manager_idstring (uuid)nullableEmployee ID of the manager; must be inside the key's scope. Later it changes only through the approval flow in the product.
statusstringactive (default) or pre_start. pre_start requires hire_date, which must be after today. Values: active, pre_start
position_idstring (uuid)nullablePosition; must be a position of the company.
hire_datestring (date)nullableHire date (YYYY-MM-DD).
service_start_datestring (date)nullable
sgk_entry_datestring (date)nullable
employment_typestringnullableEmployment type. Values: full_time, part_time, temporary, intern
probation_endstring (date)nullable

Responses

201 Created

employees.create: Responses
FieldTypeDescription
idstring (uuid)requiredID of the employee record.
company_idstring (uuid)requiredThe employee's company.
org_unit_idstring (uuid)requirednullableThe employee's unit; null when there is none.
job_title_idstring (uuid)requirednullableJob title; null when there is none.
position_idstring (uuid)requirednullablePosition; null when there is none.
manager_idstring (uuid)requirednullableEmployee ID of the manager. Null when the manager is a record the key cannot see.
first_namestringrequired
last_namestringrequired
work_emailstringrequirednullableWork email; null when there is none.
statusstringrequiredactive: employed; pre_start: hired, first day not reached; inactive: inactive; terminated: left. Values: active, pre_start, inactive, terminated
employment_typestringrequirednullable Values: full_time, part_time, temporary, intern
hire_datestring (date)requirednullableHire date.
service_start_datestring (date)requirednullable
sgk_entry_datestring (date)requirednullable
probation_endstring (date)requirednullable
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_idstringnullableNational 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.
ibanstringnullableIBAN 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.
salaryobjectnullableThe 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.
personalobjectPersonal 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 409: idempotency_in_progress, conflict
  • 413: payload_too_large
  • 415: unsupported_media_type
  • 422: idempotency_key_reused
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

employees.get: Parameters
FieldTypeDescription
id (path)string (uuid)requiredID of the employee record.

Responses

200 Successful

employees.get: Responses
FieldTypeDescription
idstring (uuid)requiredID of the employee record.
company_idstring (uuid)requiredThe employee's company.
org_unit_idstring (uuid)requirednullableThe employee's unit; null when there is none.
job_title_idstring (uuid)requirednullableJob title; null when there is none.
position_idstring (uuid)requirednullablePosition; null when there is none.
manager_idstring (uuid)requirednullableEmployee ID of the manager. Null when the manager is a record the key cannot see.
first_namestringrequired
last_namestringrequired
work_emailstringrequirednullableWork email; null when there is none.
statusstringrequiredactive: employed; pre_start: hired, first day not reached; inactive: inactive; terminated: left. Values: active, pre_start, inactive, terminated
employment_typestringrequirednullable Values: full_time, part_time, temporary, intern
hire_datestring (date)requirednullableHire date.
service_start_datestring (date)requirednullable
sgk_entry_datestring (date)requirednullable
probation_endstring (date)requirednullable
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_idstringnullableNational 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.
ibanstringnullableIBAN 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.
salaryobjectnullableThe 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.
personalobjectPersonal 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

employees.update: Parameters
FieldTypeDescription
id (path)string (uuid)requiredID of the employee record.

Request body

employees.update: Request body
FieldTypeDescription
first_namestringFirst name (1-100 characters).
last_namestringLast name (1-100 characters).
work_emailstring (email)nullableWork email; unique among active employees (a clash is 409).
org_unit_idstring (uuid)nullableUnit; must be a unit of the company.
job_title_idstring (uuid)nullableJob title.
position_idstring (uuid)nullablePosition; must be a position of the company.
hire_datestring (date)nullableHire date (YYYY-MM-DD).
service_start_datestring (date)nullable
sgk_entry_datestring (date)nullable
employment_typestringnullableEmployment type. Values: full_time, part_time, temporary, intern
probation_endstring (date)nullable
effective_datestring (date)The day a unit, position or title change takes effect; today when omitted.

Responses

200 Successful

employees.update: Responses
FieldTypeDescription
idstring (uuid)requiredID of the employee record.
company_idstring (uuid)requiredThe employee's company.
org_unit_idstring (uuid)requirednullableThe employee's unit; null when there is none.
job_title_idstring (uuid)requirednullableJob title; null when there is none.
position_idstring (uuid)requirednullablePosition; null when there is none.
manager_idstring (uuid)requirednullableEmployee ID of the manager. Null when the manager is a record the key cannot see.
first_namestringrequired
last_namestringrequired
work_emailstringrequirednullableWork email; null when there is none.
statusstringrequiredactive: employed; pre_start: hired, first day not reached; inactive: inactive; terminated: left. Values: active, pre_start, inactive, terminated
employment_typestringrequirednullable Values: full_time, part_time, temporary, intern
hire_datestring (date)requirednullableHire date.
service_start_datestring (date)requirednullable
sgk_entry_datestring (date)requirednullable
probation_endstring (date)requirednullable
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_idstringnullableNational 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.
ibanstringnullableIBAN 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.
salaryobjectnullableThe 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.
personalobjectPersonal 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 409: idempotency_in_progress, conflict
  • 413: payload_too_large
  • 415: unsupported_media_type
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout