Articles on: API

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.

Updated on: 14/05/2025

Was this article helpful?

Thank you!