❕

Required query parameters for employees.

• companyUid - Uid of a platform.
• employeeUid - Uid of an employee.

Employee

When using the Zenegy API, it is possible to set up CRUD operations for employee profiles.

Each profile consists of three parts: Base, Employment, and Salary Data. The API allows for the management of all three parts.

Retrieve employees

The API provides several endpoints to fetch employee data. For general data retrieval, we advise using the following endpoints:

Get employees array

Get employee bases.
This endpoint can be used to get a list of employee base data as an array.

Retrieve full employee details

Get employee details.
This endpoint can be used to get the full details of an employee.

The returned properties can not be limited and will always return the full details of the employee, if another endpoint in the Payroll API has the needed properties, consider using that endpoint instead.

Create and update employee(s)

🚧

Before you proceed

Many properties on an employee are directly connected to Zenegy's logic for Global value sets and Global values, using create and update methods via the API without knowledge of this logic is not advised.

Read more about Global values and sets.

The API has several endpoints for employee profile creation, making it possible only to create single profiles with simple data, bulk-create, or fully detailed single profiles.

All endpoints have the same required properties for the creation of a profile:

• CPR number of the employee.
• Name of employee.
• Employee's address.
• Employee's Postal code.
• Employee's city.
• Employment date.
• Seniority date.

Be aware that if an employee number is absent in the request, the system automatically generates one using the CPR number. For example, a CPR of 0101991212 will become an employee number like 01-01-91-xxxx.

Create a single employee

Post employee
This endpoint can be used to create a single employee. Employees can be created as simple or full profiles, depending on the values posted in the request.

📘

Simple or full profile

Depending on the values posted in the request this endpoint can be used to create a simple or a full profile. A simple profile lacks some properties required for a payroll, while a full profile includes all necessary properties.

Full profile properties

Name	Description	GV/S
cpr	CPR number, 10 characters
name	Name of Employee
address	Address of Employee
city	City of Employee address
postalNumber	Postal Number of Employee address
employmentDate	Employment date of Employee
seniorityDate	Seniority date of Employee
countryCode	Country code, 2 characters
companyCvrNumber	Company CVR
mobilePhone	Must match this regex pattern @"^[+]?\d+\s?\d*$"
email	Must match this regex pattern @"^\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$"
pNumber	10 characters, all digits
atpType	ATP types
employeeLanguage	Employee Language
salaryType	Salary types
salaryMode	Salary modes
incomeType	Income types
tax	Tax cards
revenueType	Employee types
maternityType	Maternity types
insuranceCategory	Insurance category
benefitPackageAmountType	Pension value types
holidayPaymentType	Pension value types
benefitPackageType	Benefit package types
benefitPackageTwoType	Benefit package types

GV/S properties are directly connected to Global values and sets.
Ensure all parties using the service are aware of the missing properties when creating simple profiles.

Bulk create employees

Post employees
This endpoint can be used to create several employees in a single bulk request.

The response for succesfull requests will contain an array of the UID, employee number and second employee number of the created employees.

Update Employee profile

🚧

Updating simple profiles

When updating a simple profile, it is advised to include all properties required for a full profile.

Full profile properties

Name	Description	GV/S
cpr	CPR number, 10 characters
name	Name of Employee
address	Address of Employee
city	City of Employee address
postalNumber	Postal Number of Employee address
employmentDate	Employment date of Employee
seniorityDate	Seniority date of Employee
countryCode	Country code, 2 characters
companyCvrNumber	Company CVR
mobilePhone	Must match this regex pattern @"^[+]?\d+\s?\d*$"
email	Must match this regex pattern @"^\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$"
pNumber	10 characters, all digits
atpType	ATP types
employeeLanguage	Employee Language
salaryType	Salary types
salaryMode	Salary modes
incomeType	Income types
tax	Tax cards
revenueType	Employee types
maternityType	Maternity types
insuranceCategory	Insurance category
benefitPackageAmountType	Pension value types
holidayPaymentType	Pension value types
benefitPackageType	Benefit package types
benefitPackageTwoType	Benefit package types

GV/S properties are directly connected to Global values and sets.

PATCH employee.
Expand the "path values" collapsible to see all possible values for the "path" property.

This endpoint can be used to update single or multiple properties on an employee. Only properties to be updated should be added to the payload, including other properties will cause errors in employee data
The response will not return any information when a patch request is executed. This also includes patching Global value properties.

Patching a global value will not update the data on the profile, and no error will be returned.

[
    {
        "value": "value",
        "path": "/Property",
        "op": "replace",
    }
]

Delete employees

Delete employee.

This endpoint can be used to delete a single employee from a company.
Only employees who have yet to be a part of a payroll run can be deleted. Employees that have been in a payroll run should be handled as a resignation

Deleted data cannot be restored.

Tax cards

All employee tax cards for a company can be read via the endpoint for company tax card messages.
Specific employee profile tax-cards can be read via the endpoint for employee tax card.

The response from the company-wide endpoint is filtered using OData, and the request query can be adjusted using specific filtering parameters.

API request example using OData filter

http://localhost:55500/api/companies/0551578b-e0a0-4943-8fa6-8ad6d29c33d0/employees/4aefcbc9-9314-4e3e-b3e7-ea8357173ba1/taxcards?$filter=TypeOfCard eq '1'

Enum definitions

Employee types

Salary types

Salary modes

Income types

Salary payout periods

ATP types

Employee Language

Maternity types

Insurance category

Pension value types

Benefit package types

Tax cards

Type of tax card response

Employee tax message status