Scheduling Overview

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 & Labor

To 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 employeeEmployee Shifts API
Get the shifts for a whole companyCompany Shifts API
Get the open (unassigned) shifts for a companyOpen Shifts API
Look up schedules for a companySchedules API
Create many shifts at onceBatch Shifts API
Change an existing shiftUpdate Shift API
Delete shiftsShift 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:

ProductAccess
Scheduling API Read AccessRetrieval (GET) endpoints
Scheduling Full Access APIRetrieval (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.

VersionBase pathDate/time format
V1/apiHub/scheduling/v1Offset timestamps (startDateTime, for example 2024-03-05T08:00:00-05:00)
V2/apiHub/scheduling/v2Relative timestamps (relativeStartDateTime) with no time zone information
📘

Differences between Shifts V1 & V2

AreaV1V2
Required filterstartDateTimerelativeStartDateTime
Shift timestampsstartDateTime (offset)relativeStartDateTime and relativeEndDateTime
Shift identifiersNumeric shiftId / scheduleId, plus stackIdGUID id / scheduleId
SegmentsactualTimeIn, actualTimeOut, applyToDaterelativeTimeIn, relativeTimeOut, relativeApplyToDate
Field selectionNot supported on shift endpointsfields query parameter
Template assignmenttemplateAssignmentIdtemplateVersionedAssignmentId

Update Shift and Shift Removal Requests use the shift GUID (the id returned by the V2 shift endpoints). The numeric shiftId returned 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 example 2024-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.