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: **REST
**Supported Formats: **XML
**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
User ID	1	100	❌
Login	2	50	✅
Active	False	True	❌
Position	1	100	❌
Organization Unit			❌	Valid XPHR value
Employee Group Code			❌	Valid XPHR value
Employee Group Name			❌	Valid XPHR value
Mobile App	False	True	❌
First Name	1	49	✅
Last Name	1	50	✅
State Code			❌	Valid XPHR value
State Name			❌	Valid XPHR value
Country Name			✅	Valid XPHR value
Birth Date	Current Date - 100 years	Current Date	❌	xml date & time format
Billing Rate			❌
E-mail		150	✅	Valid email address
Phone	0	100	❌
Card Number	0	255	❌	Must be unique
Attendance	False	True	❌
Time Tracking	False	True	❌
Tracking Type	1	6	❌
Default Project Code			❌	Valid XPHR value
Default Project Name			❌	Valid XPHR value
Default Activity Name			❌	Valid XPHR value
Cost Unit	Hourly	Monthly	❌
Cost Value			❌
Work Calendar Code			✅ / ❌	Valid XPHR value
Work Calendar Name			✅ / ❌	Valid XPHR value
Work Calendar Start Date			✅ / ❌
Admin			❌
Project Admin			❌
HR Admin	Org. Unit Name		❌	Valid XPHR value
Line Manager	Org. Unit Name		❌	Valid XPHR value
Project Manager	Project Name		❌	Valid XPHR value
Absence Type Code			❌	Valid XPHR value
Absence Type Name			❌	Valid XPHR value
Absence Limit Year			❌
Absence Limit Value	0		❌
Cost Center Assignment - Code			❌	Valid XPHR value
Cost Center Assignment - Valid From			❌	Required when assigning a Cost Center

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, Name, and Start Date are required when creating new employees. For updates, these values are not required.

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: 16/03/2025

Was this article helpful?

Thank you!