List employees

Returns a paginated list of employees, including their categories and dynamic attributes, filterable by the fields exposed on the employee record.

Availability: Full version and ZEP Clock

Request

GET /api/v1/employees

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 limit instead. Any value given here is replaced by limit, or by the default when limit is 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
personal_number[]
Type
array of string, nullable
Description

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": "Herr"
      },
      "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",
      "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"
          }
        }
      ],
      "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.
One of: "Herr", "Frau", ""
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 center the employee’s time and expenses are booked against.
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 type field (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
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.

Generated from the OpenAPI specification — edit the source code, not this page.

Employees GET Get a single employee