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 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.
API Type: REST
Supported Formats: XML
API Key: Generated in the app configuration
Method: Get , Post
The Get All Users endpoint allows you to retrieve the full list of employees registered within the system.
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.
This endpoint allows you to update the information of an existing employee.
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
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.
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 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 | No | |
| Login | 2 | 50 | Yes | |
| Active | False | True | No | |
| Position | 1 | 100 | No | |
| Organization Unit | - | - | No | Valid XPHR value |
| Employee Group Code | - | - | No | Valid XPHR value |
| Employee Group Name | - | - | No | Valid XPHR value |
| Mobile App | False | True | No | |
| First Name | 1 | 49 | Yes | |
| Last Name | 1 | 50 | Yes | |
| State Code | - | - | No | Valid XPHR value |
| State Name | - | - | No | Valid XPHR value |
| Country Name | - | - | Yes | Valid XPHR value |
| Birth Date | Current Date - 100 years | Current Date | No | xml date & time format |
| Billing Rate | - | - | No | |
| - | 150 | Yes | Valid email address | |
| Phone | 0 | 100 | No | |
| Card Number | 0 | 255 | Must be unique | |
| Attendance | False | True | No | |
| Time Tracking | False | True | No | |
| Tracking Type | 1 | 6 | No | |
| Default Project Code | - | - | No | Valid XPHR value |
| Default Project Name | - | - | No | Valid XPHR value |
| Default Activity Name | - | - | No | Valid XPHR value |
| Cost Unit | Hourly | Monthly | No | |
| Cost Value | - | - | No | |
| Work Calendar Code | - | - | Yes / No | Valid XPHR value |
| Work Calendar Name | - | - | Yes / No | Valid XPHR value |
| Work Calendar Start Date | - | - | Yes / No | |
| Admin | - | - | No | |
| Project Admin | - | - | No | |
| HR Admin | Org. Unit Name | - | No | Valid XPHR value |
| Line Manager | Org. Unit Name | - | No | Valid XPHR value |
| Project Manager | Project Name | - | No | Valid XPHR value |
| Absence Type Code | - | - | No | Valid XPHR value |
| Absence Type Name | - | - | No | Valid XPHR value |
| Absence Limit Year | - | - | No | |
| Absence Limit Value | 0 | - | No | |
| Cost Center Assignment - Code | - | - | No | Valid XPHR value |
| Cost Center Assignment - Valid From | No | 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/02/2025
Thank you!