Prerequisites

In order to build an integration with our ATS, you will need to have a set of Integration Partner API keys. To speak with someone about getting test credentials, please reach out to [email protected]. You will need to supply us with two endpoints (one for fetching product lists and another for placing orders), as well as a PNG image of your organization's logo for display when users place an order.

Data Flow

Our background check integration workflow depends on a standardized data flow model between the ATS, a background check integration partner, and the applicant. That data flow is outlined below:

Authentication

There exists a need for the background check partner to know which client account is being used in the API queries. The ATS Anywhere platform expects for client authentication to be handled through Basic Authorization in the HTTP request header, and for the Background Check Provider to provide a client Account ID and client API Secret which would be used for that authentication.

Getting available background check packages

A successful integration starts with the ability for our system to query data on the background check packages available. The ATS accepts a list of packages, where each package is a data object which includes the following properties:

• ID - The ID that will be sent to the Background Check Provider as part of a background check order of that package
• Name - The human-readable name that will be displayed in the UI
• Price (Optional) - A decimal value of the cost of this order to the client.
• Description (Optional) - The human-readable long description that will be displayed in the UI
• Screenings (Optional) - a list of short descriptions of screenings that will be performed as part of that package.

The ATS also accepts a second (optional) data structure called add_on_packages, which can be used in the case that the Background Check Provider offers supplemental services that may be ordered alongside any package, where each object is expected to have these properties:

• ID - The ID that will be sent to the Background Check Provider as part of a background check order of that package
• Name - The human-readable name that will be displayed in the UI
• Price - A decimal value of the cost of this order to the client.
• Description - The human-readable long description that will be displayed in the UI

{
  'packages': [
    {
      'id': "PKG001",
      'name': "Basic Package",
      'price': "29.99",
      'description': "A basic background check screening",
      'screenings': [
        "Address to Federal Criminal History (7 year)",
      ]
    },
    {
      'id': "PKG002",
      'name': "Standard Package",
      'price': "49.99",
      'description': "A basic background check screening",
      'screenings': [
        "Address to Federal Criminal History (7 year)",
        "Social Security Address/Alias Trace",
      ]
    },
    {
      'id': "PKG003",
      'name': "Deluxe Package",
      'price': "69.99",
      'description': "A basic background check screening",
      'screenings': [
        "Address to Federal Criminal History (7 year)",
        "Social Security Address/Alias Trace",
        "OFAC Specially Designated Nationals",
        "USA CriminalSearch and USA Offender",
      ]
    }
  ],
  'add_on_packages': [
    {
      'id': "DRG01",
      'name': "Basic Drug Screening", 
      'price': "29.99", 
      'description': "A 7 panel urine test for prohibited substances"
    },
    {
      'id': "DRG02",
      'name': "Comprehensive Drug Screening", 
      'price': "39.99",
      'description': "A comprehensive 10 panel urine test for prohibited substances"
    }
  ]
}

With that data structure sent back, our ATS will be able to dynamically render your product options to the client through the UI.

Sending the order to the Background Check Provider

When an order is placed, our ATS expects to send out an order to the Background Check Provider's system. Our standard payload is the following JSON structure, send via a POST request to the orders URL that the Background Check Provider will provide.

{
  'account_id': "ACCT123",
  'hiring_manager_user_id': "67890",
  'background_check_id': "224466",
  'package_id': "PKG001",
  'add_on_package_ids': ["DRG02"],
  'webhook_url': "https://api.applicant-tracking.com/yourco_webhooks",
  'hiring_manager': {
    'id': "67890",
    'first_name': "Jill",
    'last_name': "Smith",
    'email': "[email protected]"
  },
  'applicant': {
    'id': "12345",
    'first_name': "John",
    'last_name': "Doe",
    'phone': "888-555-1234",
    'email': "[email protected]",
    'address': "123 Main St.",
    'address_2': "Apt. 1",
    'city': "Springfield",
    'state': "IL",
    'zip': "12345"
  },
  'job': {
    'id': "12345"
  }
}

Our system expects a 201 response. You will store the background_check_id as a means of being able to track the background check through both systems effectively. In the case of an error, our system will expect a non 201 response with a JSON response structure that includes an error_message key.

Updating the ATS with Status Changes/Results

As the applicant moves through the background check process, the ATS expects to receive an update when the background check is complete. Updates may be made via webhooks through the URL that is specified when the background check order is initially sent to the the Background Check Provider's system. The ATS platform expects a webhook payload in the structure below:

{
  'background_check_id': ATS_Background_Check_ID,
  'status': 'complete',
  'result': 'Pass',
  'result_link_url': "https://yourco.com/background_checks/YOUR_TRACKING_ID/results"
}

📘

Need Help?

Get stuck or have questions? See our FAQs (below), contact our support team at this-address, or post your questions on stackoverflow.