Articles on: API

Employee API

The Employee API in XperienceHR enables seamless management of employee data through an external integration. It allows systems to retrieve, create, and update employee records within the platform, ensuring efficient HR data synchronization.

This API is particularly useful for organizations that need to automate employee data handling, such as onboarding new employees, updating roles, and managing workforce details in real time. It supports XML & JSON format for structured data exchange and requires authentication via an API key.

With the Employee API, businesses can integrate their HR systems with XperienceHR, improving efficiency and reducing manual data entry.

Overview

API Type: Supported Formats: XML, JSON

API Key: Generated in the app configuration

Method: Get, Post

User Management

Get All Users

The Get All Users endpoint allows you to retrieve the full list of employees registered within the system.

Endpoint

Get Users Filtered by Parameters

Parameter	Type	Description
employeeLogin	string	The login of the employee.
firstName	string	The first name of the employee.
lastName	string	The last name of the employee.
active	boolean	Indicates whether the employee is active.
userId	string	A unique, admin-modifiable ID of the employee (not the system generated ID).
cardId	string	The card ID of the employee
position	string	The employee’s position.
birthday	string	The employee’s birthdate (format: yyyy-mm-dd).
workCalendar	string	The name of the employee’s work calendar
project	string	The name of the project employee is assigned to
activity	string	The name of the activity
manager	string	The name of the employee’s manager.
organizationUnit	string	The name of the organization unit.
getSubOUEmployee	boolean	When set to true, this retrieves employees from sub-organizational units. The default value is false.

Endpoint

Create New User

Parameter	Min	Max	Required	Information
userId	1	100	❌
login	2	50	✅
languageCode			❌
active	False	True	❌
position	1	100	❌
OrganizationUnit			❌	Valid XPHR value
PayTypeGroup			❌	Valid XPHR value
mobileApp	False	True	❌
firstName	1	49	✅
lastName	1	50	✅
State code, name			❌	Valid XPHR value
Country name			✅	Valid XPHR value
birthDate	Current Date - 100 years	Current Date	❌	xml date & time format
billingRate			❌
email		150	✅	Valid email address
phone	0	100	❌
cardNr	0	255	❌	Must be unique
attendance	False	True	❌
timetracking	False	True	❌
attendanceTrackingType	1	6	❌
DefaultProject code, name			❌	Valid XPHR value
DefaultActivity name			❌	Valid XPHR value
Cost unit, value	HOUR	MONTH	❌
WorkCalendar code			✅ / ❌	Valid XPHR value
workCalendarStart			✅ / ❌
admin	False	True	❌
projectAdmin	False	True	❌
HrAdmin	Org. Unit Name		❌	Valid XPHR value
LineManager	Org. Unit Name		❌	Valid XPHR value
ProjectManager	Project Name		❌	Valid XPHR value
AbsenceType code, name, year, value			❌	Valid XPHR value
CostCenter code, validFrom			❌	Required when assigning a Cost Center
FoodVoucher enabled, value, employeeContribution			❌

Date format: YYYY-MM-DD

Attendance Tracking Types: 1 = NFC, 2 = Clock In/Out, 3 = Interval, 4 - WiFi, 5 = NFC + Clock In/Out, 6 = NFC + Clock In/Out + Wifi

Work Calendar Code and Start Date are required when creating new employees. For updates, these values are not required.

Full request examples are available below under XML Body and JSON Body 💡

API Input Code	Role Name
admin	Administrator
projectAdmin	Project Administrator
HrAdmin	HR Administrator
HrJunior	HR Manager
HrReadOnly	Assistant HR Manager
LineManager	Line Manager
ProjectManager	Project Manager
ProjectManagerJunior	Assistant Project Manager

Endpoint

Update User

This endpoint allows you to update the information of an existing employee.

Endpoint

Error Handling

Common errors help in debugging and correcting API usage issues.

Example 1: Invalid Work Calendar

Example 2: Missing Required Email Field

Example 3: Unknown Attendance Tracking Type

HTTP Response Codes

2XX Success - Operation completed successfully.
4XX Client Error - Likely an issue with the request, such as incorrect parameters or insufficient permissions. Returns an error message in text or XML format.
5XX Server Error - Indicates a server issue. Report this error if encountered.

Updated on: 15/08/2025

Was this article helpful?

Thank you!