Introduction

The flow looks as follows:

AUTHENTICATION FLOW

Request for Access token

API consumers need a Bearer token to authenticate their requests. To obtain this token, they are expected to send POST request to access_token endpoint.

The request should follow Basic Authentication standards with the following credentials:

Username (Client ID): client_id
Password (Client Secret): client_secret

Credentials should be encoded and stored in request headers.

A successful request can expect the following response:

{
  "access_token": "SFMyNTY.dncndjkek"
}

This Access token is valid for 15 minutes and is necessary for all calls from Authenticated flow.

AUTHENTICATED FLOW

Listing available jobs

An authenticated GET request is triggered towards Equalture to fetch your available jobs. These jobs have to be created first in the Equalture platform with type "assessment" and have to be published. Each job is described through a unique identifier and name.

{  
  "jobs": [  
    {  
      "id": "1234-1234-1234-1234",  
      "name": "First assessment job - Engineer"  
    },  
    {  
      "id": "1234-1234-4567-1111",  
      "name": "Second job - Accountant"  
    }  
  ]  
}

One job ID per application can be selected. See below how this job ID is used to create an application.

Creating an application

Equalture provides consumers a way to create an application for an applicant on demand. To accomplish this, a POST request with the following payload is expected:

{
  "job_id": "1234-1234-4567-1111",
  "callback_url": "https://CONSUMER_URL/applications/{id}",
  "applicant_details": {
    "first_name": "Rembrandt",
    "last_name": "Van Rijn",
    "email": "[email protected]",
  },
}

job_id: The ID for one of your job postings provided in step 1 Listing Available Jobs.
callback_url: The URL in which Equalture can publish the results (see below)
applicant_details: Applicant info. These details are used for the assessment invitation email.

Following a successful request, Equalture will respond with status 201 and provide a reference_id like so:

{"reference_id": "1234-1234-4567-1111"}

reference_id The identifier (UUID) of the application just created by the POSTrequest.

Receiving application results upon completion

Equalture will update your "callback_url" with a PUT request once we've confirmed the applicant has completed our assessments. This URL will lead Equalture users to the applicant's profile and results within our Dashboard.

Note: The callback_url endpoint should return a 200 status when successfully executed.

[Optional] This callback URL can be authenticated by a Token once provided to Equalture. Please get in touch with us to set this up.

The update payload has the following structure:

{   
 "results_url": "https://api.equalture.com/applications/000000",
 "scores": {
      "Cognitive trait": "(5) Very flexible",
      "Bahavioural style": "(2) Somewhat intuitive"
    }
  }

results_url: Link to the Equalture dashboard with applicant profile results. This is an authenticated link, login needed. For no-login option see below.

scores: Summary of traits and scores of an applicant. For more information about the way of scoring, please get in contact.

4a. Requesting a public link

To receive a public URL to view the applicant results, API consumers can use a GET request and receive a publicly accessible profile link. The link specified in the response is valid for two hours. This allows consumers to generate a link to the Equalture profile without having to give all their users access to the Equalture platform.

The request will need to follow the following format:

{
  "locale": "en",
  "reference_id": "7777-555-23123-1231"
}

locale: (Optional) Language code to view the requested profile in.

reference_id: ID of the application to view.

A successful request can expect the following response:

{"url": "https://equalture_url.com/en/candidate_results/:reference_id/summary?token=TOKEN"}

4b. Requesting results

To receive an authenticated URL to view the applicant results and the results in JSON form, API consumers can use a GET request and receive the assessment results along with a link to the Equalture platform. The link specified in this response requires to use to have access to the Equalture platform.

The request will need to follow the following format:

{
  "locale": "en",
  "reference_id": "12314-4231-ab21-1231"
}

locale: (Optional) Language code to view the requested profile in.

reference_id: ID of the application to view.

A successful request can expect the following response:

{   
 "results_url": "https://dashboard.equalture.com/:locale/link_to_profile/:id",
 "scores": {
      "Cognitive trait": "(5) Very flexible",
      "Bahavioural style": "(2) Somewhat intuitive"
    }
  }