Get a single employee
Returns one employee by their username, including the count of their absences.
include embeds the employment periods, regular working times and internal rates (not available with a Clock licence).
Availability: Full version and ZEP Clock
Request
curl --request GET \
--url 'https://www.zep-online.de/zepinstanz/next/api/v1/employees/{username}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'Path parameters
- Name
username- Type
- string
- Description
The employee username
Query parameters
- 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.
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
}
}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.