> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.xperiencehr.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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 |  |  | ❌ | Use MONTH for monthly salary; use `billingRate` field for hourly pay. |
| 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.