Introduction

The Background Check API product enables you to integrate background checks into Paylocity’s platform, receive the screening request, and post updates to a screening order.

Using the Background Check API product, you can build an integrated experience that allows Paylocity’s customers to:

Onboard to your integrated solution via Paylocity’s integration marketplace.
Initiate background checks on candidates or employees when needed.
Receive real-time updates for the screenings they have initiated.

Implementing Background Check

Step 1: Client Onboarding

The client onboarding/status API enables Paylocity to capture the status of a customer who wants to onboard with your integration. They either fill out the new account form on your web application or provide the credentials of their existing account to onboard with your integrated application. Paylocity will pass the companyId in the redirect url to you in this fashion - ?paylocityCompanyId=<user's company id>.

This allows us to pass the companyId to you systematically and helps you easily keep track of the leads as well. Once the account is approved, you should pass the status back to Paylocity so that we can update the integration status.

The table below explains the order and service statuses with the relevant definitions.

Status	Definition
InProgress	New account: This statue should be sent when the Paylocity customer has filled up the application form on your web application and submitted it for your team’s review. Existing account: For a customer which has an existing account, you may skip sending this status if they are using their existing login credentials.
Approved	New account: This status should be sent when you have approved the account request in your application. Existing account: This status should be sent when the existing login credentials have been verified successfully.
Rejected	New/Existing account - This status should be sent when the application for an account has been rejected. Note: Do not use this status to indicate the mutual customer offboarding/churning off from your platform.

Step 2: Subscribe for event alerts

This API endpoint allows you to register a callback URL where you can receive the candidate information used to initiate the background screening process. The subscription endpoint allows you to read, write, and delete the callback URL when needed.

The subscription endpoint needs to respond within 20 seconds with an HTTP status indicating the success (200) or failure (4xx or 5xx).

Step 3: Screening Package

This is for the operations for screening packages. A Package is essentially a combined group of screening services that Paylocity’s customer will be paying for. As an example, a Package could be “Basic” which includes SSN trace, county and state criminal record service, and professional history checks which could cost a customer $40 per order. A background check partner platform can combine several such components, which are individual services, and bundle up into a single package with unique name and ID. The pricing of these packages will be as per the negotiated term between the background screening partner and Paylocity.

A POST on the /packages endpoint inserts or updates a list of the packages defined for Paylocity’s customers. As a screening partner, you can also remove any package which is not active by using the IsActive flag to remove the package information from Paylocity’s UI. Paylocity will prevent any future orders using this package id, however, any in-flight screening order should still be processed by your platform.

Paylocity can support different screening packages for every company you partner with. If the company is b6001 in the request URL then the screening packages will be applicable for all the Paylocity companies, however, if you want to send screening packages at a company level then use the specific companyId in the request which will allow you granular control on your offerings to our mutual customers.

Step 4: Candidate Screening Orders

A candidate is an individual who will go through the background check process as part of the recruitment, onboarding, or compliance related events. Paylocity will post the candidate information for screening using the webhook URL registered by the background check provider.

Paylocity is not responsible for candidate compliance nor PII. It is the sole responsibility of the background vendor to ensure that all compliance and PII steps are completed on their side. To ensure this, Paylocity recommends that the background check partners capture the candidate’s consent and the relevant PII data via their web/mobile experience. Paylocity will provide basic candidate information to the background check partner so that you can initiate the next steps in the journey by contacting the candidate via email or text messages.

Callback URL: The URL registered by your company to receive the candidate information for processing the screening request.

The table below explains the order and service statuses with the relevant definitions.

Order Status	Definition
Ordered	Default status when the screening request is submitted. Screening partner doesn’t have to send this back to PCTY since it’s the default status.
WaitingOnCandidate	When the screening partner has initiated the screening process by emailing the candidate.
InProgress	When the candidate or employee has submitted the information required for screening. At this point the screen is in progress, and we are waiting for the background vendor to complete the orders.
Hold	When more information is requested from the candidate or employee to run the screening.
Complete	When the screen is complete. At this point all the underlying service orders are completed (e.g., SSN trace, MVR, education verification, etc.) and a final report is available to the client.
PreAdverseActionSent	When the pre-adverse action is initiated by the recruiter via the partner application.
AdverseActionCancelled	When the adverse action is cancelled after the review.
Dispute	When candidate disputes the adverse action.
AdverseActionSent	When the adverse action is final, and the notice is sent.

The table below shows statuses of underlying services (e.g., SSN trace, MVR, education verification, etc.) of screening order.

Services Status	Definition
Pending	Default status when the screening request is submitted. Screening partner doesn’t have to send this back to PCTY since it’s the default status.
InProgress	When the candidate or employee has submitted the information required for screening. At this point the screen is in progress, and we are waiting for the background vendor to complete the orders.
Completed	When the screening for an underlying service is complete. Note: This does not mean that the order is complete. It only represents that the included screening within the package is complete.