Introduction

APIs serve as the essential mechanism that ensures seamless integration between our software and other systems, facilitating smooth and efficient operations.

Ensuring the ongoing enhancement and security of our software is crucial. By retiring outdated features and introducing improvements, we aim to provide you with a more resilient and adaptable experience. The deprecation of APIs allows us to stay ahead of evolving needs and standards.

We strive to make the API transformation process both engaging and understandable. Our commitment is to be your reliable partner, guiding you with confidence through these changes.

What is API versioning?

API versioning is a process of managing, tracking, and effectively communicating changes of an API to its consumers.

Change is a normal aspect of API development. Developers may need to update the API to address security vulnerabilities or to introduce new features. While some updates do not impact users, others—known as “breaking changes”—can cause backward compatibility issues, leading to unexpected errors or data corruption. Effective API versioning helps ensure that these changes are implemented smoothly, maintaining consumer trust while keeping the API secure, efficient, and free of bugs.

Versioning Strategy

At Paylocity, we use URL versioning when updating our APIs, meaning that the version number is included in the URL of the API endpoint.

As an example, if an integration needed to view employee information in our sandbox environment, it would send the request to our Employee Demographic API at the following endpoint with appropriate parameters specified:

https://dc1demogwext.paylocity.com/coreHr/v1/companies/{companyId}/employees/{employeeId}

Paylocity API Lifecycle

General Availability (GA)

The API is accessible and ready for production use. It is backed with ongoing support for any new features and bug fixes in subsequent releases, which follow the Paylocity versioning process. Comprehensive documentation for GA functionality is also available.

Deprecated (12-months)

The API undergoes deprecation as the initial step toward retirement. This typically occurs at least 12 months before permanent retirement of the API. Documentation is maintained for deprecated APIs during these 12 months either with references to newer implementations or clear notes if a functionality is being removed completely.

The API retains support for bug fixes but no longer undergoes enhancements during this stage. Although the API is accessible, building new solutions with deprecated APIs is not advised.

During this stage, we introduce a Warning header to API responses, which serves as an alert to make you aware of the deprecation timeline and the status of the API, facilitating proper planning and transition. Monitoring Warning headers in HTTP responses is recommended.

X-Pcty-Warning: "299"
X-Pcty-Warning-Message": "This endpoint has been deprecated and will not be accessible on or after the provided date."
Sunset: 2024-09-25T00:00:00Z
Deprecated: 2025-09-25T00:00:00Z
Link: <https://developer.paylocity.com/deprecation-list>;
         rel="deprecation"; type="text/html"

Retired

The API and relevant technical documentation are no longer accessible, and proactive support of the API is no longer available.