Ensure Data is Current

Always ensure your records are the most up-to-date available. If a user modifies their punch data in Paylocity, you must update your backend system accordingly to maintain data accuracy.

Retrieve Data by Shift Start Date

To avoid duplicate data, your system should only retrieve shifts that share the same start date. Follow this process to avoid duplicate data:

1. Query the timespan wanted
2. Retrieve results
3. Only process records with a start date within the time range.

Use a Consistent Time Frame

When filtering shifts, specify a clear shift start time. For example, filter from the start of the business day (e.g., August 3rd, 9 a.m.) to the end of the day (e.g., 11:59 p.m.). Data will be concise when filtered from the previous day and not include additional punches from the following day.

Handle Overnight Shifts

If any part of the overnight shift is within the timespan, Punch Details will return the entire shift, not just the parts within the timespan.⁣

Prevent Duplicate Punches

To ensure you don't retrieve duplicate punches, you should filter by both the shift's start date and the punch ID in your backend system. This dual-filter approach provides a unique identifier, preventing your system using the same data multiple times.

Encourage Real-Time Punch Logging:

• Promote employees to log punches at the start and end of their shifts rather than batching time entries at the end of the week. This practice supports real-time data availability, enhances accuracy, and reduces the risk of errors during reconciliation.

Operations

• Only one company-level Punch Detail operation can be in a running state at any given time. Additional requests are queued and processed on a first-in, first-out (FIFO) basis.

Rate Limits & Best Practices

To ensure system reliability and performance, our API platform enforces the following rate limits:

• 300 Requests per minute, with a burst rate of 5 requests per second.

The API will respond with a 429 (Too Many Requests) status code if the rate limit is exceeded. These limits are designed to maintain platform stability and support consistent usage.

Best Practices for Efficient Punch Detail API Usage

Query Data After Shifts Conclude:

• Schedule API calls shortly after shifts (day, afternoon, or evening) to capture complete and accurate punch data. This approach reduces the risk of incomplete data being retrieved due to in-progress synchronization.

Allow a Buffer of 10–15 Minutes Post-Shift:

• Wait approximately 10–15 minutes beyond the hour when a shift concludes before querying the API. This ensures all punch data has synchronized across systems, providing the most accurate results. It also gives employees a timeframe to finish out their shift and correct a punch if needed.