REST DocumentationEmployeesGET List employees

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

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
    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 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
    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.

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