Create an employee

Creates a new employee record.

Availability: Full version and ZEP Clock

Request

POST /api/v1/employees

curl --request POST \
     --url 'https://www.zep-online.de/zepinstanz/next/api/v1/employees' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {token}' \
     --header 'Content-Type: application/json' \
     --data '{
       "username": "max.mustermann",
       "firstname": "Max",
       "lastname": "Mustermann",
       "email": "erika.mustermann@acme-corp.de",
       "personal_number": "1",
       "birthdate": "1985-08-17T00:00:00.000000Z",
       "phone": "+49 30 12345678",
       "password": "1234",
       "department_id": 1,
       "rights": 0,
       "employment": 0,
       "price_group": "Junior-Entwickler",
       "oauth_username": "string",
       "salutation": "Herr",
       "street": "Musterstraße 30",
       "zip": "71254",
       "city": "Berlin",
       "country": "Deutschland",
       "abbreviation": "MM",
       "title": "Dr.",
       "mobile": "+49 170 1234567",
       "fax": "+1-555-0124",
       "private_phone": "07156 33958",
       "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,
       "personio_id": "string",
       "connector_external_ids": [
         "string"
       ],
       "cost_bearer": "string",
       "tax_id": "string",
       "creditor_number": "80033",
       "cost_accounting_ads": true,
       "categories": [
         "string"
       ],
       "dynamicAttributes": [
         [
           "string"
         ]
       ]
     }'

Request body

Name
username
Type
string, required
Description
Unique login name to create the employee under.
Name
firstname
Type
string, required
Description
Given name of the new employee.
Name
lastname
Type
string, required
Description
Family name of the new employee.
Name
email
Type
string (email), required
Description
Business email address the new employee is invited under.
Name
personal_number
Type
string, nullable
Description
The employee’s personnel number, as printed on the payslip.
Name
birthdate
Type
string (date-time), nullable
Description
Date of birth of the new employee.
Name
phone
Type
string, nullable
Description
Business landline phone number.
Name
password
Type
string, required
Description
Initial login password, randomly generated when omitted.
Name
department_id
Type
integer, nullable
Description
Identifier of the department to assign the new employee to.
Name
rights
Type
integer, nullable
Description
Access-rights level to grant the new employee in the application.
One of: 0, 1, 2, 3, 4, 5, 11
Name
employment
Type
integer, nullable
Description
Type of employment (permanent, freelance, …).
One of: 0, 1, 2
Name
price_group
Type
string, required
Description
Price group the new employee’s billing rates are derived from.
Name
oauth_username
Type
string, nullable
Description
Username used to match the employee against an external OAuth identity.
Name
salutation
Type
string, nullable
Description
Form of address (Mr, Ms, …) used when addressing the employee.
One of: "Herr", "Frau", "Divers"
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
title
Type
string, nullable
Description
Academic or professional title, if any.
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
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
personio_id
Type
string, nullable
Description
Identifier of the employee in the connected Personio HR system, if linked.
Name
connector_external_ids
Type
array of string, nullable
Description
External identifiers this employee is matched against per connector.
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
creditor_number
Type
string, nullable
Description
Creditor number used when reimbursing the employee via accounting.
Name
cost_accounting_ads
Type
boolean, nullable
Description
Whether the employee’s cost accounting is submitted via ADS.
Name
categories
Type
array of string, nullable
Description
Categories to assign the new employee to.
Name
dynamicAttributes
Type
array of array, nullable
Description
Custom dynamic attributes to set on the new employee.

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

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.

GET Get a single employee PATCH Update an employee