API Reference
Start typing to search…

Introduction

Introduction into the Equalture Open Assessment API. This API is used to connect your platform to work with the Equalture platform.

Here's how the flow works:

Grab your token for using the API


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

  1. 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.

GET /connect_ats/jobs

A successful request will return the following 200 response:

[  
  {  
    "id": "UUID",  
    "name": "First assessment job - Engineer"  
  },  
  {  
    "id": "UUID",  
    "name": "Second job - Accountant"  
  }  
]

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

  1. 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:

POST /connect_ats/applications
{
  "job_id": "JOB_UUID",
  "callback_url": "https://CONSUMER_URL/applications/{your_uuid}",
  "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.


Invitation types

  1. Email

If you provide email as an invitation_type, an applicant will receive an email with an invitation link. Applicant will have 1 week to access a link, which is sent in the email.

  1. One time link

If you provide one_time_link as an invitation_type, Equalture will respond with status 201 and provide a link to the assessment:

{
  reference_id: "d2c37d4d-b8d4-46a9-b230-42a246ad6153",
  assessment_url: "https://app.equalture.com/en/assessments/73799/token/SFMyNTY.g2gDaAJ3DGFwcGxpY2FudF9pZG0AAAAkMzYxNDdlMmEtZTBhOS00MDQ0LWFmZmUtYzkxZmY1YWZhNWRhbgYAXtBqrJQBYgABUYA.3NH7lWKETUNlvqfxKZvXfI2fL-pWX9FUDI62LH9mEy39392"
}

Applicant will have 1 week to access the above link.


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.

ional] Thi 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://dashboard.equalture.com/applications/:uuid",
  "scores": {
    "Cognitive trait": "(5) Very flexible",
    "Bahavioural style": "(2) Somewhat intuitive"
  },
  "fit": "low",
  "detailed_scores": [
    {
      "competency_profile": {
        "priority": "low",
        "range": [1, 2, 3, 4, 5]
      },
      "trait_bucket_description": "(3) Neutraal",
      "trait_bucket_score": 3,
      "trait_code": "problem_solving_style",
      "trait_name": "Probleemoplossende stijl"
    },
    {
      "competency_profile": {
        "priority": "medium",
        "range": [1, 2, 3]
      },
      "trait_bucket_description": "(5) Hogere capaciteit",
      "trait_bucket_score": 5,
      "trait_code": "problem_solving_ability",
      "trait_name": "Probleemoplossend vermogen"
    }
  ]
}

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.

fit: Shows the fit for the applicant with the job based on the connect competency profile.

detailed_scores: Explains the scoring more in details including the ranges for the connected competency profile.


  1. Hiring an applicant

To hire an applicant, API consumers should send a POST request to the endpoint corresponding to the target application. This operation updates the application status to hired and triggers any additional configured processes as described below.

POST /connect_ats/applications/{reference_id}/hire_applicant

reference_id: The identifier (UUID) of the application returned from the POST application request.


The request takes the following body params:

{
  "add_to_team": "true",
  "start_date": "2025-07-01"
}

add_to_team: (Required) Determines whether the applicant should be added to the associated team upon hiring. If set to true and the job has a team, the applicant is added to it. If false, the applicant is hired without team assignment.

start_date: (Optional) The date when the applicant's contract officially begins. This value should be provided in ISO 8601 format (YYYY-MM-DD) and represents the start of the applicant's employment or contractual engagement.


A successful request will return the following 200 response:

{
  "message": "Applicant has been successfully hired and added to team if configured",
  "reference_id": "1234-1234-4567-1111"
}

  1. Deleting an application

To anonymize an applicant's application, API consumers should send a DELETE request to the endpoint corresponding to the target application. This operation sets the application status to anonymized, preventing associated scores from being viewed.

DELETE /connect_ats/applications/{reference_id}/anonymize_application

reference_id: The identifier (UUID) of the application returned from the POST application request.


A successful request will return the following 200 response:

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

5a. Requesting a public link

To receive a public URL to view the applicant results, API consumers should send 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.

GET /connect_ats/applications/{reference_id}/public_link

reference_id: The identifier (UUID) of the application returned from the POST application request.


The request takes the following query params:

{ "locale": "en" }

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


A successful request can expect the following 200 response:

{
  "url": "https://equalture_url.com/en/candidate_results/:reference_id/summary?token=TOKEN",
  "ttl": "120",
  "ttl_units": "minutes"
}

5b. Requesting results

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

GET /connect_ats/applications/{reference_id}/results

reference_id: The identifier (UUID) of the application returned from the POST application request.


The request takes the following query params:

{ "locale": "en" }

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


A successful request can expect the following 200 response:

{   
  "fit": "high",
  "results_url": "https://dashboard.equalture.com/:locale/candidates/:id",
  "scores": {
      "Cognitive trait": "(5) Very flexible",
      "Bahavioural style": "(2) Somewhat intuitive"
  },
  "detailed_scores": [
    {
      "competency_profile": {
        "priority": "medium",
        "range": [
          2,
          3,
          4,
          5
        ]
      },
      "trait_bucket_description": "(3) Average",
      "trait_bucket_score": 3,
      "trait_code": "working_memory",
      "trait_name": "Learning ability/Working memory"
    }
	]
}

5c. Requesting status

To retrieve the status of an application, API consumers should send a GET request to the corresponding application resource. The response indicates whether the application is completed, with results available, or still in progress.

GET /connect_ats/applications/{reference_id}/status

reference_id: The identifier (UUID) of the application returned from the POST application request.


A successful request can expect the following 200 response:

{ "status": "completed" }