List employees
Returns a paginated list of employees, including their categories and dynamic
attributes, filterable by the fields exposed on the employee record. include embeds the
employment periods, regular working times and internal rates (not available with a Clock
licence) of each employee, complete and unpaged. With include=internal_rates, modified_after also finds an employee whose internal rate
changed, and modified_before leaves out one whose internal rate changed after the bound; a
deleted internal rate leaves no timestamp, so catching deletions needs a full comparison.
Availability: Full version and ZEP Clock
Request
curl --request GET \
--url 'https://www.zep-online.de/zepinstanz/next/api/v1/employees' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'Query parameters
- Name
perPage- Type
- integer, nullable
- Description
Ignored on this endpoint — send
limitinstead. Any value given here is replaced bylimit, or by the default whenlimitis absent.
- Name
page- Type
- integer, nullable
- Description
The page of results to return, counting from 1.
- Name
orderBy- Type
- string, nullable
- Description
Name of the field to sort by.
- Name
order- Type
- string, nullable
- Description
Sort direction, ascending or descending.
One of:
"asc","desc"
- Name
limit- Type
- integer, nullable
- Description
The number of records per page, 1 to 200. Defaults to 15.
- Name
modified_after- Type
- string (date-time)
- Description
Only return records modified after this timestamp (ISO 8601, or “Y-m-d H:i:s”).
- Name
modified_before- Type
- string (date-time)
- Description
Only return records modified before or at this timestamp (ISO 8601, or “Y-m-d H:i:s”).
- Name
include- Type
- string, nullable
- Description
Comma-separated sub-lists to embed in each employee: employment_periods, regular_working_times, internal_rates (not available with a Clock licence). The lists are complete, not paged. On the list, include=internal_rates makes modified_after also match an employee whose internal rate changed, and modified_before excludes one whose rate changed after the bound; a deleted internal rate is not detected.
- Name
personal_number[]- Type
- array of string, nullable
- Description
- Name
employed- Type
- string, nullable
- Description
Restrict the result by employment: true returns only employees with an employment period on the reference day, false all others, including employees without any period.
One of:
"true","false","1","0"
- Name
employed_on- Type
- string (date), nullable
- Description
Reference day for employed (Y-m-d), today by default. A period that starts or ends on that day counts. It is ignored without employed.
Response
{
"data": [
{
"username": "max.mustermann",
"firstname": "Max",
"lastname": "Mustermann",
"personal_number": "1",
"street": "Musterstraße 30",
"zip": "71254",
"city": "Berlin",
"country": "Deutschland",
"abbreviation": "MM",
"salutation": {
"id": "string",
"name": "string"
},
"title": "Dr.",
"email": "erika.mustermann@acme-corp.de",
"phone": "+49 30 12345678",
"mobile": "+49 170 1234567",
"fax": "+1-555-0124",
"private_phone": "07156 33958",
"birthdate": "1985-08-17T00:00:00.000000Z",
"iban": "DE89370400440532013000",
"bic": "COBADEFFXXX",
"account_no": "string",
"bank_name": "string",
"bank_code": "string",
"currency": "EUR",
"approval_date": "2026-01-31T09:00:00.000000Z",
"vat": 1.5,
"price_group": "Junior-Entwickler",
"employment": {
"id": "string",
"name": "Mitarbeiter/in"
},
"rights": {
"id": "string",
"name": "User"
},
"department_id": 1,
"language": {
"locale": "string",
"isoCode": "de",
"name": "deutsch",
"dateFormat": "d.m.Y",
"dateTimeFormat": "d.m.Y H:i",
"numberFormat": {
"decimalSeparator": "string",
"thousandsSeparator": "string"
}
},
"personio_id": "string",
"cost_bearer": "string",
"cost_center": "4711",
"note": "Familienurlaub",
"overtime_ads": true,
"tax_id": "string",
"created": "2024-07-20T11:30:00.000000Z",
"modified": "2024-07-20T12:30:00.000000Z",
"creditor_number": "80033",
"categories": [
{
"name": "EU",
"description": {
"de": "string",
"en": "string",
"fr": "string",
"es": "string",
"pl": "string"
},
"type": {
"id": "string",
"name": "Mitarbeiter/in"
}
}
],
"dynamicAttributes": [
{
"name": "EU",
"value": "Max Mustermann (Bruder)",
"type": "Text",
"description": {
"de": "string",
"en": "string",
"fr": "string",
"es": "string",
"pl": "string"
}
}
],
"employment_periods": [
{
"id": 1,
"employee_id": "max.mustermann",
"start_date": "2024-01-01",
"end_date": null
}
],
"regular_working_times": [
{
"id": 1,
"employee_id": "max.mustermann",
"start_date": "2024-01-01",
"monday": 8
}
],
"internal_rates": [
{
"id": 1,
"employee_id": "max.mustermann",
"start_date": "2024-01-01",
"internal_rate": 85.5
}
],
"absences_count": 1,
"regularWorkingTimes_count": 1,
"employmentPeriods_count": 1,
"internalRates_count": 1
}
],
"links": {
"first": "string",
"last": "string",
"prev": "string",
"next": "string"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"links": [
{
"url": "string",
"label": "string",
"active": true
}
],
"path": "string",
"per_page": 1,
"to": 1,
"total": 1
}
}Response fields
- Name
username- Type
- string
- Description
Unique login name of the employee, also used as their identifier in the API.
- Name
firstname- Type
- string
- Description
Given name of the employee.
- Name
lastname- Type
- string
- Description
Family name of the employee.
- Name
personal_number- Type
- string, nullable
- Description
The employee’s personnel number, as printed on the payslip.
- Name
street- Type
- string, nullable
- Description
Street and house number of the employee’s address.
- Name
zip- Type
- string, nullable
- Description
Postal code of the employee’s address.
- Name
city- Type
- string, nullable
- Description
City of the employee’s address.
- Name
country- Type
- string, nullable
- Description
Country of the employee’s address.
- Name
abbreviation- Type
- string, nullable
- Description
Short mnemonic used to identify the employee in compact views and reports.
- Name
salutation- Type
- object, nullable
- Description
Form of address (Mr, Ms, …) used when addressing the employee.
- Name
salutation.id- Type
- string
- Description
The stored value. Compare against this, not against name.
- Name
salutation.name- Type
- string
- Description
The human-readable label, delivered in the tenant’s language. Do not parse it.
- Name
title- Type
- string, nullable
- Description
Academic or professional title, if any.
- Name
email- Type
- string, nullable
- Description
Business email address the employee is reachable and invited under.
- Name
phone- Type
- string, nullable
- Description
Business landline phone number.
- Name
mobile- Type
- string, nullable
- Description
Business mobile phone number.
- Name
fax- Type
- string, nullable
- Description
Business fax number.
- Name
private_phone- Type
- string, nullable
- Description
Personal phone number, kept separate from the business phone number.
- Name
birthdate- Type
- string (date-time), nullable
- Description
Date of birth of the employee.
- Name
iban- Type
- string, nullable
- Description
International Bank Account Number used for reimbursements and payroll.
- Name
bic- Type
- string, nullable
- Description
Bank Identifier Code of the employee’s bank.
- Name
account_no- Type
- string, nullable
- Description
Bank account number, used when IBAN is not available.
- Name
bank_name- Type
- string, nullable
- Description
Name of the employee’s bank.
- Name
bank_code- Type
- string, nullable
- Description
Routing code of the employee’s bank.
- Name
currency- Type
- string, nullable
- Description
Currency the employee’s rates and reimbursements are expressed in.
- Name
approval_date- Type
- string (date-time), nullable
- Description
Date the employee’s data/contract was approved.
- Name
vat- Type
- number, nullable
- Description
Value-added tax rate applied to the employee’s billed rates.
- Name
price_group- Type
- string
- Description
Price group the employee’s billing rates are derived from.
- Name
employment- Type
- object, nullable
- Description
Type of employment (permanent, freelance, …).
- Name
employment.id- Type
- string
- Description
The stored value. Compare against this, not against name.
- Name
employment.name- Type
- string
- Description
The human-readable label, delivered in the tenant’s language. Do not parse it.
One of:
"Mitarbeiter/in","Freier Mitarbeiter","Freier Mitarbeiter mit Gutschrift"
- Name
rights- Type
- object
- Description
Access-rights level granted to the employee in the application.
- Name
rights.id- Type
- string
- Description
The stored value. Compare against this, not against name.
- Name
rights.name- Type
- string
- Description
The human-readable label, delivered in the tenant’s language. Do not parse it.
One of:
"User","Administrator","Controller","User with additional authorizations","Projektcontroller","Kundenansprechpartner","System-Administrator"
- Name
department_id- Type
- integer
- Description
Identifier of the department the employee currently belongs to.
- Name
language- Type
- object, nullable
- Description
Language the employee’s interface and communication are shown in.
- Name
language.locale- Type
- string
- Description
- Name
language.isoCode- Type
- string
- Description
One of:
"de","en","fr","es","pl","sk","tr"
- Name
language.name- Type
- string
- Description
One of:
"deutsch","German (Austria)","German (Switzerland)","englisch","English (German Format)","English (Europe)","English (Great Britain)","English (USA)","französisch","French (Switzerland)","French (German Format)","Spanisch","Polnisch","Slovak","Turkish"
- Name
language.dateFormat- Type
- string
- Description
One of:
"d.m.Y","d/m/Y","m/d/Y"
- Name
language.dateTimeFormat- Type
- string
- Description
One of:
"d.m.Y H:i","d/m/Y H:i","m/d/Y H:i"
- Name
language.numberFormat- Type
- object
- Description
- Name
personio_id- Type
- string, nullable
- Description
Identifier of the employee in the connected Personio HR system, if linked.
- Name
cost_bearer- Type
- string, nullable
- Description
Cost bearer the employee’s time and expenses are booked against.
- Name
cost_center- Type
- string, nullable
- Description
Cost center (Kostenstelle) the employee belongs to; not the same as the cost bearer.
- Name
note- Type
- string, nullable
- Description
Free-text note about the employee.
- Name
overtime_ads- Type
- boolean, nullable
- Description
Whether the employee’s overtime is displayed; null when never set.
- Name
tax_id- Type
- string, nullable
- Description
Tax identification number of the employee.
- Name
created- Type
- string (date-time), nullable
- Description
Timestamp the employee record was created.
- Name
modified- Type
- string (date-time), nullable
- Description
Timestamp the employee record was last modified.
- Name
creditor_number- Type
- string, nullable
- Description
Creditor number used when reimbursing the employee via accounting.
- Name
categories- Type
- array of Category
- Description
Categories the employee is assigned to.
- Name
categories.name- Type
- string
- Description
Name of the category, shown wherever an entity is tagged with it.
- Name
categories.description- Type
- object
- Description
Longer explanation of what this category should be used for.
- Name
categories.type- Type
- object
- Description
The kind of entity this category can be attached to, e.g. employee, project or customer.
- Name
dynamicAttributes- Type
- array of DynamicAttribute
- Description
Custom dynamic attributes configured for this tenant and set on this employee.
- Name
dynamicAttributes.name- Type
- string
- Description
Name of the dynamic attribute definition this value was entered for.
- Name
dynamicAttributes.value- Type
- any
- Description
The stored value; its shape depends on the neighbouring
typefield (a string, a number, a boolean, a date, an employee reference, or a list of option values).
- Name
dynamicAttributes.type- Type
- string
- Description
The data type of this attribute, e.g. text, number, date or options, which decides how to interpret
value.One of:
"Text","Integer","Float","URL","E-Mail","Datum","Uhrzeit","Datetime","Boolean","Betrag","Optionen","Prozent","Time period","Textarea","Users","Upload"
- Name
dynamicAttributes.description- Type
- object, nullable
- Description
Explanation of what this attribute captures, as configured on its definition.
- Name
employment_periods- Type
- array of EmploymentPeriod
- Description
The employee’s employment periods, same shape as the employment-periods endpoint. Only present with include=employment_periods; the list is complete, not paged.
- Name
employment_periods.id- Type
- integer
- Description
Unique identifier of the employment period.
- Name
employment_periods.employee_id- Type
- string
- Description
Username of the employee this employment period belongs to.
- Name
employment_periods.start_date- Type
- string (date-time), nullable
- Description
First calendar day the employee was employed under this period.
- Name
employment_periods.end_date- Type
- string (date-time), nullable
- Description
Last calendar day the employee was employed under this period, if it ended.
- Name
employment_periods.note- Type
- string, nullable
- Description
Free-text note attached to the employment period.
- Name
employment_periods.beginning_of_year- Type
- string (date-time), nullable
- Description
Calendar day the leave year begins on for this employment period.
- Name
employment_periods.annual_leave_entitlement- Type
- number, nullable
- Description
Number of vacation days the employee is entitled to per full leave year.
- Name
employment_periods.period_holiday_entitlement- Type
- number, nullable
- Description
Number of vacation days the employee is entitled to, prorated for this period.
- Name
employment_periods.is_holiday_per_year- Type
- boolean, nullable
- Description
Whether the annual leave entitlement is expressed per calendar year rather than per employment period.
- Name
employment_periods.day_absent_in_hours- Type
- number, nullable
- Description
Number of hours a full day of absence is booked as for this employment period.
- Name
employment_periods.created- Type
- string (date-time), nullable
- Description
Timestamp the employment period was created.
- Name
employment_periods.modified- Type
- string (date-time), nullable
- Description
Timestamp the employment period was last modified.
- Name
regular_working_times- Type
- array of RegularWorkingTime
- Description
The employee’s regular working times, same shape as the regular-working-times endpoint. Only present with include=regular_working_times; the list is complete, not paged.
- Name
regular_working_times.id- Type
- integer
- Description
Unique identifier of the regular working-time schedule.
- Name
regular_working_times.employee_id- Type
- string
- Description
Username of the employee this schedule applies to.
- Name
regular_working_times.start_date- Type
- string (date-time), nullable
- Description
Calendar day this schedule takes effect from.
- Name
regular_working_times.monday- Type
- number, nullable
- Description
Planned working hours on Monday.
- Name
regular_working_times.monday_workday- Type
- boolean, nullable
- Description
Whether Monday counts as a workday for this schedule.
- Name
regular_working_times.tuesday- Type
- number, nullable
- Description
Planned working hours on Tuesday.
- Name
regular_working_times.tuesday_workday- Type
- boolean, nullable
- Description
Whether Tuesday counts as a workday for this schedule.
- Name
regular_working_times.wednesday- Type
- number, nullable
- Description
Planned working hours on Wednesday.
- Name
regular_working_times.wednesday_workday- Type
- boolean, nullable
- Description
Whether Wednesday counts as a workday for this schedule.
- Name
regular_working_times.thursday- Type
- number, nullable
- Description
Planned working hours on Thursday.
- Name
regular_working_times.thursday_workday- Type
- boolean, nullable
- Description
Whether Thursday counts as a workday for this schedule.
- Name
regular_working_times.friday- Type
- number, nullable
- Description
Planned working hours on Friday.
- Name
regular_working_times.friday_workday- Type
- boolean, nullable
- Description
Whether Friday counts as a workday for this schedule.
- Name
regular_working_times.saturday- Type
- number, nullable
- Description
Planned working hours on Saturday.
- Name
regular_working_times.saturday_workday- Type
- boolean, nullable
- Description
Whether Saturday counts as a workday for this schedule.
- Name
regular_working_times.sunday- Type
- number, nullable
- Description
Planned working hours on Sunday.
- Name
regular_working_times.sunday_workday- Type
- boolean, nullable
- Description
Whether Sunday counts as a workday for this schedule.
- Name
regular_working_times.is_monthly- Type
- boolean, nullable
- Description
Whether the schedule is defined as a monthly total instead of per weekday.
- Name
regular_working_times.monthly_hours- Type
- number, nullable
- Description
Planned working hours per month, only set when the schedule is monthly.
- Name
regular_working_times.max_hours_in_month- Type
- number, nullable
- Description
Maximum working hours allowed per month under this schedule.
- Name
regular_working_times.max_hours_in_week- Type
- number, nullable
- Description
Maximum working hours allowed per week under this schedule.
- Name
regular_working_times.holidayCalendar- Type
- object (HolidayCalendar)
- Description
Holiday calendar this schedule’s public holidays are drawn from.
- Name
regular_working_times.breakRegulationType- Type
- object (BreakRegulationType)
- Description
Break regulation applied when calculating breaks for this schedule.
- Name
internal_rates- Type
- array of InternalRate
- Description
The employee’s internal rates, same shape as the internal-rates endpoint. Only present with include=internal_rates; the list is complete, not paged.
- Name
internal_rates.id- Type
- integer
- Description
Unique identifier of the internal rate.
- Name
internal_rates.employee_id- Type
- string
- Description
Username of the employee this internal rate applies to.
- Name
internal_rates.start_date- Type
- string (date-time)
- Description
Calendar day this internal rate takes effect from.
- Name
internal_rates.internal_rate- Type
- number, nullable
- Description
Internal (cost) rate charged for the employee’s time.
- Name
internal_rates.note- Type
- string, nullable
- Description
Free-text note attached to the internal rate.
- Name
internal_rates.monthly_rate- Type
- number, nullable
- Description
Fixed monthly rate, used instead of the hourly rate when applicable.
- Name
internal_rates.internal_rate_resets- Type
- number, nullable
- Description
Interval at which the internal rate resets (e.g. monthly, yearly).
- Name
internal_rates.rate_type- Type
- object, nullable
- Description
Whether the rate is charged hourly or as a fixed monthly amount.
- Name
internal_rates.created- Type
- string (date-time), nullable
- Description
Timestamp the internal rate was created.
- Name
internal_rates.modified- Type
- string (date-time), nullable
- Description
Timestamp the internal rate was last modified.
- Name
absences_count- Type
- integer
- Description
Number of absences recorded for this employee.
- Name
regularWorkingTimes_count- Type
- integer
- Description
Number of regular working-time schedules recorded for this employee.
- Name
employmentPeriods_count- Type
- integer
- Description
Number of employment periods recorded for this employee.
- Name
internalRates_count- Type
- integer
- Description
Number of internal rates recorded for this employee.