Assessment Integrations

Prerequisites

In order to build an integration with our ATS, you will need to do the following:

  1. Obtain a set of Integration Partner API keys. To speak with someone about getting test credentials, please reach out to [email protected]
  2. Provide two URLS: one that we will use to fetch a list of available assessments, and one that we will use to place orders.
  3. For each account that will be connected to your integration, you will need to provide us with API credentials specific to that account. See the Authentication section below.

Data Flow

Our assessment vendor integration workflow depends on a standardized data flow model between the ATS, an assessment partner, and the applicant. Assessments may be ordered in one of two ways:

Automatic Orders: Managers may choose to have an assessment ordered automatically for each applicant who applies to a given job. In such cases, once an application is complete, the applicant will be presented with a link to the assessment.

Manual Orders: If an assessment was not automatically ordered, or if an assessment needs to be re-ordered, a manager may order assessments manually at any time after an applicant has applied. In such cases, the applicant will be emailed a link to the assessment.

That data flow is outlined below:

Diagram of the data flow between the ATS platform, the assessment provider, and the applicant.Diagram of the data flow between the ATS platform, the assessment provider, and the applicant.

Diagram of the data flow between the ATS platform, the assessment provider, and the applicant.

Authentication

There exists a need for the assessment 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 Assessment Provider to provide a client Account ID and client API Secret which would be used for that authentication.

Getting available assessment packages

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

  • ID - The ID that will be sent to the Assessment Provider as part of an assessment order of that package
  • Name - The human-readable name that will be displayed in the UI
{
  'assessments': [
    {
      'id': "ASMT001",
      'name': "Skills Assessment",
    },
    {
      'id': "ASMT002",
      'name': "Personality Assessment",
    },
    {
      'id': "ASMT002",
      'name': "Skills + Personality Assessment",
    }
  ]
}

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 Assessment Provider

When an order is placed, our ATS expects to send out an order to the Assessment Provider's system. Our standard payload is the following JSON structure, send via a POST request to the URL that the Assessment Provider will need to provide at the time of integration go-live.

{
  'account_id': "ACCT123",
  'assessment_id': "112233",
  'product_id': "PKG001",
  'job_id': "123",
  'redirect_url': "https://api.applicant-tracking.com/partners/assessments/112233",
  'applicant': {
    'id': "12345",
    'first_name': "John",
    'last_name': "Doe",
    'email': "[email protected]",
  },
}

Our system expects a 201 response, with a JSON response structure that includes the following key:
{ assessment_link: YOUR_LINK_TO_THE_ASSESSMENT }. A job applicant will use this link to take the assessment as ordered.

Updating the ATS with Status Changes/Results

As the applicant moves through the assessment process, the ATS expects to receive updates with the latest status of the assessment process. You can access & update assessment records through our Partner API (https://api.atsanywhere.io/reference). The record is able to be accessed/updated through that API with just your API keys. The ID for the assessment resource is sent (as shown above) along with the initial request to initiate the assessment.