Integrating Background Checks

Audience:

Labels:

None assigned

Recruiting & Hiring can integrate with any background check vendor. 

 How It Works: Recruiting & Hiring sends key data points about the person to the background check vendor, and the vendor, whenever able, sends back a report. This integration leverages the existing order-entry process of background check vendors and eliminates much of the complexity surrounding traditional HR-XML based integrations.

Accessing Background Checks

The background check functionality can be located within each applicant's profile. From there, you can select the Background Checks option in the left navigation bar.

1.png

This selection allows a user to view results from previously requested checks, and it includes the option to make a new request. 

2.png

Running a Background Check 

To run a new background check, click New "Your Provider Name" BGC button. This selection will prompt the system to post a JSON string to any URL you provide in a new window.

The following screenshots illustrate what will occur:

2ndBackgroundSim2Final.png

 Authenticate

As a first step, you will want to reauthenticate the user, as Recruiting & Hiring does not pass credentials other than the current user’s email address. This means you will first enter the email address affiliated with the user in question and click Sign In to proceed.

Example of a login instance: 4.png

 Add Details (Optional)

After authenticating your user, you will likely want to get into an order entry process. This means you may want additional information about the applicant for which the order is being placed. If so, make an API call (as illustrated in the technical details further below). 

Once the order is placed, the system will indicate a confirmation message, as noted here:

5.png

 Issue Notification of Completion 

You should indicate the successful authentication to the user and notify Recruiting & Hiring via a web service call that the order has been placed.

Updates sent via webservice calls are displayed to the user on the applicant’s profile.

Once Recruiting & Hiring receives the completed post back from your system, the Status section will reflect the result of the check and a “View” link will be displayed that points the user to the report URL you provide.

6.png

Process Overview

The following diagram depicts how Recruiting & Hiring and your service should interact:

7.png

Technical Details

 Step 1

As outlined above, the user in Recruiting & Hiring clicks the “Order Background Check” button, and this selection prompts Recruiting & Hiring to open a new window and to perform a browser-based POST to any URL you desire.

The posted content will appear as follows:  
ATSUserName=ProviderCustomerId&ATSCandidateID=CurrentApplicant.AppNo&ATSUserEmail =CurrentUser.Email  
Note: *CurrentUser.Email will likely be formatted with URL-escaped characters (example: %40 for @).  

 Step 2:

The background check vendor may then authenticate the user and collect order details. When the order has either been created or exists as a draft/in-progress state, the background check vendor should POST back to Recruiting & Hiring that an order has been started for this person.

Post to URL:  
https://www.applitrack.com/[ClientCode]/onlineapp/8acknowledgecbc.aspx?Provider=[ProviderID]  

Consider the following terms in relation to this URL:

  • [ClientCode] is the unique identifier for Frontline Recruiting & Hiring clients. We will provide one for a testing environment when we initially set up the integration, and we will provide client-specific codes to you as individual clients begin using it.
  • [ProviderID] is our unique identifier for you as a background check provider. We will provide this to you when we initially set up the integration.
 
Post the following XML message:  

<?xml version="1.0" encoding="utf-16" ?>
<Response>
   <ATSCandidateID>0000</ATSCandidateID>
   <OrderID>00000</OrderID>
   <Status>Draft</Status>
   <Message>Any message to be displayed by Recruiting & Hiring regarding this order.</Message>
   <ReportURL></ReportURL>
</Response>

 

Consider the following requirements in relation to this XML message:

  • The ATSCandidateID in the XML post must match the number provided by Recruiting & Hiring in the JSON post’s ATSCandidateID.
  • OrderID will be provided by your system and is the unique identifier for an individual background check request/report.
  • As this stage is a “Draft”, we assume no URL is yet available.
 

 Step 3

In order to find out more information about the person/subject of the order, and ultimately place the order, the background check vendor may call out to Recruiting & Hiring's general API to download additional details we have on file. Please reach out to our Technical Services group at for more information, including our documentation on the R&H API.

Note: The information sent to a vendor ultimately depends upon that vendor's background verification process and what information they require. These data points are based on the API calls issued during Steps 2 and 3. 

 Step 4

When the order is complete, return the report to Recruiting & Hiring.

Post to URL:  
https://www.applitrack.com/[ClientCode]/onlineapp/8acknowledgecbc.aspx?Provider=[ProviderID]  
Note: This is the same URL from Step 2.  
Post a similar XML message:  
<?xml version="1.0" encoding="utf-16" ?>
<Response>
   <ATSCandidateID>0000</ATSCandidateID>
   <OrderID>00000</OrderID>
   <Status>Complete</Status>
   <Message>Any message to be displayed by Recruiting & Hiring regarding this order.</Message>
   <ReportURL>The URL to the report provided by your system.</ReportURL>
</Response>
 
Note: The ATSCandidateID and OrderID in this XML message must match the values provided in the message from step 2. Otherwise, Recruiting & Hiring will consider this a different background check report.  

 Step 5

Recruiting & Hiring will then expect to show the full background check report via the report URL that was returned. The user will be directed to the ReportURL when they click the View button.