Paylocity Authentication and Integration Guide

Paylocity 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, 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 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 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 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 if you don't already have one.

Once registered, you submit a request for API access, 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:

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:

{ 
  "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:

curl --location 'https://api.paylocity.com/api/v2/companies/{COMPANY_ID}/employees' \
--header 'Authorization: Bearer <AUTH_TOKEN>'

Replace COMPANY_ID with your company ID and AUTH_TOKEN with an active access token.

You should get a response similar to the following:

[
  {
    "employeeId": "123abc",
    "statusCode": A,
    "statusTypeCode": 1,
  }
]

Using the retrieved employee IDs, you can make an iterative call to get the pay statements of each employee in your company, as illustrated in this JavaScript example:

const getProcessedEmployeePayrollData = async (companyId, year, checkDate) => {
  try {
    // Set headers
    const headers = {
      Authorization: `Bearer ${process.env.PAYLOCITY_API_KEY}`,
    };

    // Fetch employee data
    const response = await fetch(
      `https://api.paylocity.com/api/v2/companies/${companyId}/employees`,
      { headers }
    );
    const employeeData = await response.json();

    // Fetch payroll data for each employee
    const employeePayrollData = await Promise.all(
      employeeData.map((employee) =>
        fetch(
          `https://api.paylocity.com/api/v2/companies/${companyId}/employees/${employee.id}/paystatement/details/${year}/${checkDate}`,
          { headers }
        ).then((res) => res.json())
      )
    );

    return employeePayrollData;
  } catch (err) {
    console.error(err);
  }
};

The preceding code block defines a getProcessedEmployeePayrollData function, which fetches all the employees in your company and iterates over the list to fetch each of their pay statements.

For each employee, the function should return a response similar to the following:

[
  {
    "amount": 4500.75,
    "checkDate": "2024-09-15",
    "det": "Salary Payment",
    "detCode": "SAL20240915",
    "detType": "Monthly",
    "eligibleCompensation": 4500.75,
    "hours": 160,
    "rate": 28.13,
    "transactionNumber": 10345,
    "transactionType": "Credit",
    "year": 2024
  }
]

With the received data, you can perform employee cost analysis to evaluate the total costs associated with employing staff for the specified period.

Let's explore another example. Here, you create a new employee using the Paylocity API.

Onboarding a New Employee

This example creates an employee using the Paylocity onboarding endpoint, which is typically used for prehires. However, if a new employee is considered hired from an HR perspective, the new employee endpoint would be more appropriate.

To create a new employee using the onboarding endpoint, you make a POST request using the company ID and a request body containing information about the employee, such as home address, email, salary, and employment type. The properties required for the onboarding request body are listed in the reference doc.

Here's a sample curl request to the Paylocity onboarding API to create a new employee:

curl --request POST \
     --url https://apisandbox.paylocity.com/api/v1/companies/12i22u33unr3u/onboarding/employees \
     --header 'Authorization: 3uir3r4r89ur3hr39r3984rfur' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "firstName": "test",
  "lastName": "employee",
  "userName": "testersInc"
}
'

You should get a success message indicating that the employee has been created successfully.

After you complete your integrations, you can test it in the sandbox environment provided by Paylocity. The sandbox environment mimics real-life scenarios, allowing you to identify and fix any possible issues before moving forward.

Finally, after you have tested your integration and fixed all possible issues, you need to submit your integration for review. After the review process, Paylocity should approve your integration, allowing you to go live.

Conclusion

In this article, you explored the Paylocity API, its use cases, its limitations and possible challenges, and the process to access and authenticate your requests. Additionally, you learned how to integrate the Paylocity API with your solution using an employee cost analysis report as an example.

The Paylocity API integration process can be simplified using the Apideck HRIS API. The Paylocity connector abstracts most of the complexity and maintenance associated with directly integrating Paylocity. For example, Apideck monitors the expiration time of the access token. When it expires, a new access token is automatically requested for you.

To get started with the Apideck Paylocity connector, sign up to Apideck.