Integrating Background Checks

Audience:

Labels:

None assigned

Applicant Tracking can integrate with any background check vendor. 

 How It Works: Applicant Tracking 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 Applicant Tracking 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 Applicant Tracking via a web service call that the order has been placed.

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

Once Applicant Tracking 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 Applicant Tracking and your service should interact:

7.png

Technical Details

 Step 1

As outlined above, the user in Applicant Tracking clicks the “Order Background Check” button, and this selection prompts Applicant Tracking 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 Applicant Tracking 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 Applicant Tracking 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 Applicant Tracking 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 Applicant Tracking 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 Applicant Tracking’s general API to download additional details we have on file. Please refer to Frontline’s documentation on the R&H API for more information.

 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 Applicant Tracking.

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 Applicant Tracking 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, Applicant Tracking will consider this a different background check report.  

 Step 5

Applicant Tracking 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.