Company and Employee Shifts, Schedules, Batch Shift Creation, Shift Updates and Shift Removal
Early Access (EA)This API has endpoints that are currently in Early Access (EA) and available only to approved EA participants. Do not rely on endpoints marked as EA for production workloads unless explicitly authorized. If you have any feedback, please share with your designated Early Adoption program representative.
Introduction
The Scheduling API product provides access to shift and schedule data at both the company and employee levels, and lets you create, update, and remove shifts.
It supports the following operations:
- Retrieve the shifts for a single employee within a specified timeframe.
- Retrieve the shifts for an entire company within a specified timeframe.
- Retrieve the open (unassigned) shifts for a company within a specified timeframe.
- Retrieve the schedules defined for a company.
- Create shifts in bulk (batch) for one or more employees.
- Update a single shift.
- Remove one or more shifts.
Getting Started
Enabling Time & LaborTo use the Time & Labor APIs in your sandbox environment, the corresponding Time & Labor features must first be enabled. This feature may be enabled by request to your assigned Paylocity support representative or Partner contact.
| I want to... | Use |
|---|---|
| Get the shifts for one employee | Employee Shifts API |
| Get the shifts for a whole company | Company Shifts API |
| Get the open (unassigned) shifts for a company | Open Shifts API |
| Look up schedules for a company | Schedules API |
| Create many shifts at once | Batch Shifts API |
| Change an existing shift | Update Shift API |
| Delete shifts | Shift Removal Requests API |
Request and response details, fields, and examples for each operation are on the individual endpoint pages.
Authentication
In the External Developer Portal (EDP), you create an application by selecting the products it needs and receive client credentials for those products. To call the Scheduling API, your EDP application must include one of these products:
| Product | Access |
|---|---|
| Scheduling API Read Access | Retrieval (GET) endpoints |
| Scheduling Full Access API | Retrieval (GET) and create/update/remove (POST, PUT) endpoints. Only available upon request for EA participants. |
Requests made with credentials from an application that does not include the required product are rejected.
API Versions
Scheduling is available in two versions. They differ mainly in how date/times are represented.
| Version | Base path | Date/time format |
|---|---|---|
| V1 | /apiHub/scheduling/v1 | Offset timestamps (startDateTime, for example 2024-03-05T08:00:00-05:00) |
| V2 | /apiHub/scheduling/v2 | Relative timestamps (relativeStartDateTime) with no time zone information |
Differences between Shifts V1 & V2
Area V1 V2 Required filter startDateTimerelativeStartDateTimeShift timestamps startDateTime(offset)relativeStartDateTimeandrelativeEndDateTimeShift identifiers Numeric shiftId/scheduleId, plusstackIdGUID id/scheduleIdSegments actualTimeIn,actualTimeOut,applyToDaterelativeTimeIn,relativeTimeOut,relativeApplyToDateField selection Not supported on shift endpoints fieldsquery parameterTemplate assignment templateAssignmentIdtemplateVersionedAssignmentIdUpdate Shift and Shift Removal Requests use the shift GUID (the
idreturned by the V2 shift endpoints). The numericshiftIdreturned by V1 cannot be used with them.
Handling Date/Times
Shift retrieval requires a date filter. The filter query parameter is mandatory, and the request returns a 400 if it is missing.
- V1 endpoints filter on
startDateTime, which is an offset timestamp that includes the UTC offset, for example2024-03-05T08:00:00-05:00. - V2 endpoints filter on
relativeStartDateTime. Relative date/times are interpreted in the time zone of the shift location, so they must be formatted without any time zone information or offset.
V2 examples:
- Start of the day:
2024-03-05T00:00:00 - End of the day:
2024-03-05T23:59:00 - Filter:
filter=relativeStartDateTime ge 2024-03-05T00:00:00 and relativeStartDateTime le 2024-03-05T23:59:00
The same relative format is used in V2 request payloads, such as relativeStartDateTime when creating or updating shifts.
Pagination
Retrieval endpoints support limit and offset. Set includeTotalCount=true to receive the total number of matching records in the X-Pcty-Total-Count response header. If that value is greater than the number of results received, call the endpoint again with an offset equal to the number of records already received, and repeat until all records are received.