Punch Import Overview

Punch Import API

The Paylocity Punch Import API integrates directly with the Paylocity Time & Labor module and streamlines the submission of employee time data from external systems.

The API provides an alternative to the two existing import methods:

• File import through the application
• File import via SFTP

Import Window

The Punch Import API supports a rolling submission window for time data, however, acceptance depends on the pay period status. Important: Time & Labor only accepts punches for open pay periods. Once a pay period is closed, external punches cannot be submitted via the API. Punches submitted outside the supported system window or for closed pay periods will be rejected.

Intended Use & Processing

• The API is intended for submitting finalized employee time data for payroll processing.
• The API does not support edits or updates to previously submitted punches.

It is strongly recommended that data be submitted only after the pay period is complete and ready for processing.

Once submitted:

• The data is processed by the Time & Labor rules engine.
• Hours worked are calculated based on configured pay rules.
• The data is imported into the Time & Labor module.
• After approval, the time is available for payroll processing.

This design ensures that externally generated time data follows the same calculation and approval workflow as time captured natively within Paylocity.

Prerequisites for Punch Import API to function

• The API user must have valid API Credentials
• API credentials must have permissions to the Punch Import API
• The customer's Time and Labor module must be live
• The cost center data sent to the Punch Import API must match what is in Time & Labor
• The client must set the API File Map as the default in Time and Labor
• The client File Map must match the data in your posted payload

Time & Labor File Map

The Time & Labor File Map is a powerful tool that streamlines the integration of time and attendance data by mapping API payload fields to the client's system configurations. Each client may have unique configurations, particularly for Record Types such as Punch In, Punch Out, and Lunch.

The File Map facilitates aligning data from the source system with the client's setup by mapping payload data to the desired number of cost centers and corresponding Record Types within the Time & Labor module. This capability is helpful when the source system has differing Record Types, as it enables mapping without requiring the development team to manually configure mappings for each client. This process reduces implementation complexity and time, ensuring accurate data integration across systems.

Limitations of the Punch Import
The Punch Import API does not currently support edits to imported punches. Edits to existing punches must be handled directly through the Time and Labor Module.

The Punch Import API has a max payload size of 500 records. If you send a payload with more than that, you will receive an error: Body is too large, must be less than or equal to 500 objects

What happens after a successful API import?

• All properly formatted submissions will return a 200 Success message
• The data will appear in the system once processing is complete. You can view the transmission details in the Time and Labor module on the Punch Import screen.
• An admin user will navigate to EMPLOYEES—PUNCH IMPORT to view the Punch Import logs in the Time and Labor module.
• The punch import screen lists all imports into the system. That includes manual imports through the UX, files imported through the SFTP process, or records imported through the API
• Any imports completed by the API will have the filename start with "API_Punch_Import," and will display like the screenshot below:

View Import Details

To view the details of a specific import, click on the eye icon in the Action column (see the above screenshot). You can view all the records provided in the API payload on the Import Results screen. You can also download a result file containing the same data in a CSV file.

View Employee Time Card Audit

Check the Audit Trail on the employee time card to confirm if a specific employee punch originated via the Punch Import API. In the "changed by" column, you will see where the API made the change.

Technical Support Resources

Support within the Time & Labor module, specifically any actions within the application. If you have calculation problems, File Map edit problems, or anything else in general with your Time & Labor module, please contact [email protected]. Please note that only an authorized contact can reach out to this address; non-authorized emails will be ignored.

Support with the Punch Import API, specifically with getting authorization, support with API error messages, or general API questions, please email [email protected]. Emails to this address automatically generate a support ticket and will be worked on in the order they are received.