---

--- title: "Paylocity Authentication and Integration Guide" description: "In this guide, you'll learn about the Paylocity API—its pitfalls, complexities, and use cases. You'll also learn to integrate it into your workflow to manage your HR tasks." author: "David Ekete" published: "2024-09-21T10:00+02:00" updated: "2025-03-26T11:14:29.369Z" url: "https://www.apideck.com/blog/paylocity-authentication-and-integration-guide" category: "HRIS" tags: ["HRIS", "Accounting", "Unified API", "Guides & Tutorials"] --- # Paylocity Authentication and Integration Guide [Paylocity](https://www.paylocity.com/) is an online payroll and human capital management (HCM) tool that streamlines and automates HR tasks like payroll, benefits administration, time and labor tracking, talent management, and employee engagement. Paylocity provides an API you can use to access and manage all the available Paylocity features. It also enables you to integrate it with other products and services, such as recruitment and applicant tracking systems (ATS) and data analytics and business intelligence tools. In this guide, you'll learn about the Paylocity API—its pitfalls, complexities, and use cases. You'll also learn to integrate it into your workflow to manage your HR tasks. ## The Paylocity API The Paylocity API allows you to programmatically access Paylocity's features, such as payroll processing and other HR-related functions. For example, you can retrieve employee demographic information, access employee payroll information, and access and update employees' scheduled payroll deductions with the API. These features are particularly useful for 401(k) providers as they make it easier to maintain a list of employees' participation in the 401(k) plan, track amounts contributed to the 401(k) plan, and ensure that elected deferrals are processed correctly during payroll processing. The Paylocity API also allows you to receive real-time notifications of new hires, terminations, and payroll processing using webhooks, enabling you to make necessary real-time updates to your system. Additionally, it provides access to processed payroll information to facilitate financial reports and general ledger (GL) journal entries and offers an employee onboarding system and timekeeping point-of-sale system. To integrate the Paylocity API with your service, you need an application that can retrieve and send data through the Paylocity API, like a unified API, such as [Apideck](https://www.apideck.com/), or a development team with experience building an API integration with the Paylocity API directly. If your solution handles personally identifiable information (PII), you also need to understand and implement security protocols and adhere to compliance requirements. The Paylocity API is not free to use; for details on the pricing, you need to contact your Paylocity account executive, who should be assigned to you upon a successful account creation. ### Challenges and Complexities of the Paylocity API Integrating the Paylocity API with your systems can come with some challenges: - **Finding the right endpoints:** The Paylocity API provides various endpoints that solve different problems in payroll and HCM, most of which might be outside your current problem set. Finding the right ones to fit your needs might be difficult. A good way to approach this challenge would be to visit the [**Common Integration Use Cases**](https://developer.paylocity.com/integrations/docs/common-use-cases-partners) page, which contains a quick reference table showing you where to find the right endpoints for your use cases. - **Receiving testing credentials:** Before receiving credentials to test your integration in a sandbox environment, you must submit an access request, which must be reviewed and approved. This process can be time-consuming and stall development time. To mitigate delays, ensure your request is complete and [fulfills Paylocity's requirements](https://developer.paylocity.com/integrations/docs/integration-requirements) before you submit it. - **Dealing with short-lived authentication tokens:** The Paylocity API authentication tokens last only an hour, after which you must request a new authentication token. This can cause issues with your solution if your integration is not properly equipped to refresh the tokens as soon as or before they expire. Implementing a robust token management system that automatically refreshes tokens and handles token expiration gracefully is crucial to ensure your system runs without authentication interruptions. - **Meeting integration requirements:** The Paylocity API has strict integration requirements that your solution needs to meet before it can go live. The requirements ensure compliance with policies and protect user data. To make sure you meet these requirements, review the Paylocity [integration documentation](https://developer.paylocity.com/integrations/v2024-07-09/docs/integration-requirements) and conduct testing and validation to ensure your integration complies with security standards, data protection regulations, and functional expectations. - **Implementing error handling:** Integrating with Paylocity API might involve dealing with various errors and exceptions. To ensure that your service does not shut down unexpectedly due to errors, you need to implement comprehensive error handling and logging mechanisms to identify and resolve issues quickly. ## Integrating the Paylocity API For this tutorial, you will integrate the Paylocity API to perform two different tasks: - Obtain employees' processed payroll details for an employee cost analysis report. - Onboard a new employee in your organization. ### Authenticating your Paylocity Requests To get started with the Paylocity API and follow along, you need a Paylocity account. You can [register for free](https://access.paylocity.com/Register) if you don't already have one. Once registered, you submit a [request for API access](https://docs.paylocity.com/Knowledge/Partner%20Integration/Paylocity%20Web%20Services_Access%20Request.pdf), which Paylocity reviews. After your request has been approved, Paylocity provides OAuth credentials and access to a sandbox account. The OAuth credentials provided should include a `company_id`, `client_id`, and `client_secret`. Store these credentials securely and ensure they are not publicly accessible as they carry many privileges. Paylocity authorizes all requests with an access token. To get an access token, you make a request to the token endpoint with your `client_id`, `client_secret`, and `grant_type`, which always has a value of `client_credentials`. Following is a sample curl request to the Paylocity token API to retrieve an access token: ```jsx curl --location 'https://gwext.paylocity.com/public/security/v1/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=dfff6fdfb9a145d59389542285dfa505' \ --data-urlencode 'client_secret=XXX123' \ --data-urlencode 'grant_type=client_credentials' ``` You should get a response similar to the following: ```jsx { "access_token": "1a2B3cxxxxxxxxxxxxxxxxxxj5", "token_type": "Bearer", "expires_in": 3600 //1 hour } ``` You can authenticate your request to other Paylocity API endpoints using this access token. ### Retrieving Processed Payrolls Let's look at how to integrate the Paylocity API to obtain employees' processed payroll details for an employee cost analysis report. To obtain employees' processed payrolls, you initially need to use the `get all employees` endpoint to retrieve a list of employee IDs, as you can see in the following curl request: ```jsx curl --location 'https://api.paylocity.com/api/v2/companies/{COMPANY_ID}/employees' \ --header 'Authorization: Bearer

---