> ## 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).

# Time Records API

The **Time Records API** in XperienceHR provides an interface for retrieving employee time records, allowing seamless integration with external systems for payroll, reporting, and attendance tracking.

This API enables businesses to access detailed records of employee working hours, including timestamps, projects, and work statuses. It supports **XML & JSON format** for structured data exchange and requires authentication via an **API key**.

By integrating the Time Records API, organizations can streamline workforce tracking, ensuring accurate work hour calculations and efficient payroll processing.

# Overview

**API Type:** REST
**Supported Formats:** XML
**API Key:** Generated in the app configuration
**Method:** *GET*
---

# Time Records

### Get All Time Records

Fetches the complete time records of employees within the system.

###### Endpoint
---

### Get Time Records Filtered by Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| ---- |
| timeFrom | string | ✅ | Start date of the time record range (format: yyyy-mm-dd, e.g., 1990-01-01). |
| timeTo | string | ✅ | End date of the time record range (format:  yyyy-mm-dd, e.g., 1990-01-01). |
| username | string | ❌ | User login name. |
| locked | boolean | ❌ | Indicates if the time record is locked. |
| includeAbsence | boolean | ❌ | Includes absence time records. |
| processId | string | ❌ | If the date range between timeFrom and timeTo exceeds 35 days, the response includes a processId to use as a parameter for additional results. |
| employeeID | string | ❌ | User ID (modifiable by admin). |
| projectName | string | ❌ | Name of the project. |
| projectCode | string | ❌ | Code of the project. |
| activityName | string | ❌ | Name of the activity. |
| activityCode | string | ❌ | Code of the activity. |
| costCenterName | string | ❌ | Name of the cost center. |
| costCenterCode | string | ❌ | Code of the cost center. |
| absenceName | string | ❌ | Name of the time-off type. |
| absenceCode | string | ❌ | Code of the time-off type. |
| status | string | ❌ | Status of the time record, either OPEN or APPROVED. (REJECTED status is not included in queries by default) |
| isBillable | boolean | ❌ | Indicates if the time record is billable. |
| absenceOnly | boolean | ❌ | Retrieves only time records with absences. |
| lastModifiedAfter | string | ❌ | Retrieves records modified after the specified date (format: yyyy-mm-dd). |

|| To use the parameters `absenceName`, `absenceCode`, or `absenceOnly`, the `includeAbsence` parameter must be set to `true`.

###### List of Possible Elements in <TimeRecord>
 
Each record typically contains the following elements:

| **Required** | **Optional** |
| ---- |
| `id` | `Client` |
| `employeeID` | `Project` |
| `login` | `EmployeeOrganizationUnit` |
| `employee` | `EmployeeCostCenter` |
| `date` | `ProjectCostCenter` |
| `timeFrom` | `note` |
| `timeTo` | `locked` |
| `workedMinutes` |  |
| `isWorkedTime` |  |
| `isBillable` |  |
| `timesheetStatus` |  |
| `status` |  |
| `version` |  |
| `position` |  |
| `country` |  |
| `billingRate` |  |
| `billingPrice` |  |
| `costRate` |  |
| `costPrice` |  |

###### Nested Elements and Their Structure

When optional elements appear, their nested structure always consistent:

`<Activity>`
* `<name>`
* `<Parent>` (only if it's a sub-activity)

`<Client>`
* `<code>`
* `<name>`

`<Project>`
* `<code>`
* `<name>`
* `<Parent>` (only if it's sub-project)

`<EmployeeOrganizationUnit>`
* `<name>`

`<EmployeeCostCenter>`
* `<code>`
* `<name>`

`<ProjectCostCenter>`
* `<code>`
* `<name>`

*Nested elements* (`<code>`, `<name>`, `<Parent>`) never change—their structure remains the same whenever they are present.

###### Stability of Structure Across Records

The nested structure and element names are consistent across all `<TimeRecord>` entries. The only variability is in the presence of optional elements (e.g., `Client`, `Project`, `EmployeeOrganizationUnit`, `EmployeeCostCenter`, `ProjectCostCenter`, `note`), which appear only when the corresponding data is available.

###### processId in 30-Day Chunks

* **Behavior**: The `processId` element is only returned when the requested date range exceeds 35 days.
* **Implication**: When fetching data in 30-day chunks, you will **not** receive a `processId`. You do not need to handle this field when using 30-day intervals.


###### Endpoint

|| `status`: This field is relevant if project timesheet approvals are used.

|| `locked`: This field only appears when a time record is locked.
---

### 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.