Introduction
Partner Restricted
All background check API endpoints are restricted to background check providers that have signed a Paylocity technology partnership agreement. Please reach out to [email protected] if you would like to discuss partnership opportunities.
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 status 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. |
| CompleteWithCancelled | Report partially completed with canceled screenings, no charges found. |
| Cancelled | All screenings canceled before processing, or automatic completion due to specific exceptions. |
| CompleteNeedsReview | Report completed, charges found. Requires review. |
| CompleteNotEligible | Report post-adverse actioned automatically. |
| Suspended | Screening suspended due to unresolved exceptions |
| Resumed | Suspended report resumed. |
| CompleteDisputed | Report disputed by the candidate. |
| InvitationExpired | Screening invite expired. |
| InvitationCancelled | Invite cancelled via Partner Dashboard. |
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. |
| Cancelled | Service was cancelled, maps to several package-level canceled statuses. |
| NeedsReview | Charges found during the service, requiring review. |
| NotEligible | Resulting from post-adverse action, matches package level. |
| Suspended | Service suspended, awaiting resolution of issues. |
| Disputed | Service result disputed by the candidate. |
| Expired | Service or invitation expired without completion. |