Introduction

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

Using the Punch Detail API product, you can build an integrated experience that allows Paylocitys customers to:

• Retrieve a single detailed record of an employee punches within a specified timeframe
• Retrieve multiple detailed records of employees punches within a specified timeframe

Getting Started

To retrieve an 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

GET Employee Punch Details API V2 endpoint provides access to a single employee punch details. Employee Punch Detail V2 offers four decimals of precision for timesheets using hours instead of minutes, allowing timesheets to display four decimal places and capturing hours with better precision. Punch times as well as non-work pay types will display up to four decimals. The Punch Details API can be filtered by the relative date and time based on your time zone.

👍

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.

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: Start the Process to Retrieve Data

Send a POST to the Company Punch Detail API. Include your company ID in the URL and a timeframe in the body .

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

Body Example:

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

This step will generate the “Location” and generate an “Operation ID” to use on the next step. The location can be found in the headers and will be formatted as a URL. The Operation ID can be found at the end of the Location URL.

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

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

Step 2: Check the Status of the Punch Details Operation

The next step is to check the status of the Punch Details Operation. Send a GET to the Location that was generated in the previous step. It will generate a payload providing the status and the Resource ID for the next step in the process. The "Resource ID" can be found at the end of the Location URL in the payload.

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

Step 3: Generate the Company Punch Detail Data

The final step is to generate the Company Punch Detail Data. Send a GET to the Company Punch Detail URL. Include the companyId, resourceId. Including a limit the number of employee punches in the payload.

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