Introduction

The Punch Detail API product provides access to punch data at both the company and employee levels.

It supports the following operations:

• Retrieve a single detailed punch record for an employee within a specified timeframe.
• Retrieve multiple detailed (company level) punch records for one or more employees within a specified timeframe.

Getting Started

To retrieve employee punch data within a specific timeframe, use the Employee Punch Detail API.

To retrieve multiple employee punch data within a specific timeframe, use the Company Punch Detail API.

---

Employee Punch Details API V2

The GET Punch Detail V2 endpoint provides access to detailed punch information for a single employee. It returns all associated punch data, including work and non‑work time entries, to support analysis and time‑record management. Punch Detail V2 uses four‑decimal precision for timesheets that track time in hours rather than seconds. For example, 7.2567 hours. Users can filter Punch Detail V2 results by relative date and time, using the time zone associated with your request.

👍

Filtering by Date Range

The Punch Details API can be filtered by the relative date and time based on your time zone. When searching punch data, users can filter up to 31 days with no limitation on searching older punch data. Dates must be formatted to not include any timezone information or the request will fail.

For example:

Start of the day: At 00:00:00 (midnight), marking the beginning of the day.

Midday: At 12:00:00 (noon), halfway through the day.

End of the day: At 23:59:00, just a second before the next day begins.

A 24 hour day is represented by using:
startDate={{relativeStartTime}}&endDate={{relativeEndTime}}

"startDate": "2024-03-05T00:00:00"

"endDate": "2024-03-05T23:59:00"

/Time/v1/companies/{{companyId}}/employees/{{employeeId}}/punchdetails?startDate={{relativeStartTime}}&endDate={{relativeEndTime}}

📘

Differences between Employee Punch Detail V1 & V2

The "durationSeconds" field has been updated to "durationHours"

Employee Punch Detail V1 uses the "durationSeconds" field to return the total seconds worked by the employee for a particular punch or time entry, reflecting the duration of their work.

Employee Punch Detail V2 uses the "durationHours" field to return the total hours worked by the employee for a particular punch or time entry, reflecting the duration of their work.

---

Company Punch Detail

Step 1: POST Create Company Punch Detail Operations

This operation begins the process of retrieving punch data for a company. This step generates the Location value and the Operation ID, which you will use in the following request.

Company Punch Detail URL: /Time/v2/companies/{{companyId}}/punchdetails

Body Example:

{
  "relativeStart":"2024-03-05T00:00:00",
  "relativeEnd":"2024-06-05T23:59:00"
}

When invoked, it returns two values:

• Location (URL) — included in the response headers
• Operation ID — found at the end of the Location URL
  Both values are required for the next step.

Location Example: /Time/v2/companies/{{companyId}}/PunchDetailOperations/{{operationId}}

Operation ID Example: d4f519bc-7401-4d73-801f-4997d7da77be

Step 2: GET Punch Details Operation

Use the Location and Operation ID returned in the previous step to check the status of the ongoing operation.
During this stage, the internal processing engine is gathering all punch data included in your request.
The operation continues until processing is complete. When finished, the status value will be succeeded.
To check the status of the Punch Details operation:

1. Send a GET request to the Location URL returned in the previous step.
2. The response payload will include:

• The current operation status
• A Resource ID required for the next step in the workflow

3. The Resource ID is located at the end of the Location URL included in the payload.

PLEASE NOTE: It can take up to several minutes for the operation to complete with the 'succeeded' status.

Response Example:

{
    "status": "succeeded",
    "created": "2024-12-13T20:42:57.587575",
    "lastUpdated": "2024-12-13T20:43:06.687066",
    "location": "https://paylocity.com/apihub/time/v2/companies/0179/PunchDetails/e81967e4-fffd-49d6-9e3a-2acc3e467ecb"
}

Resource ID Example: e81967e4-fffd-49d6-9e3a-2acc3e467ecb

Possible Statuses

Step 3: GET Punch Details Data

The final step is to generate the Company Punch Detail Data.
Send a GET request to the Company Punch Detail URL and include the following parameters:

• companyId
• resourceId
• (Optional) limit — restricts the number of employee punches returned
• (Optional) offset — defines the pagination starting point
• (Optional) sort — specifies sorting behavior

Company Punch Detail Data: /time/v2/companies/{{companyId}}/PunchDetails/{{resourceId}}?includetotalcount=true&limit=100

If the X-Pcty-Total-Count header is greater than the number of results received, then call the endpoint again with an offset equal to the number of records already received to fetch the next set of records.

For example:
If the initial fetch does not provide all the punches, the call should be repeated with an offset equal to the number of records received so far.

/time/v2/companies/{{companyId}}/PunchDetails/{{resourceId}}?includetotalcount=true&limit=100&offset=100

Then a third call can be made.

/time/v2/companies/{{companyId}}/PunchDetails/{{resourceId}}?includetotalcount=true&limit=100&offset=200

Continue in this fashion until all the records are received.