Assessio offers a simple API for approved partners to integrate with our Recruitment Module. The API allows integrators to:

• Access the list of available lenses an organisation has access to.
• Create and manage recruitments based on those lenses.
• Invite candidates to complete an assessment package containing all assessments required for evaluating the candidate against the given lens.

The primary use-case for this API is for Applicant Tracking Systems (ATS) or client-specific implementations to integrate our assessments and results within a third-party system as part of a broader candidate recruitment process.

The API is available in two environments:

• Sandbox (Testing Environment): https://sandbox.api.assessio.systems/
• Production (Live Environment): https://api.assessio.online/

Note: The sandbox environment allows integration testing without affecting live data. It may have limitations compared to production.

• Assessment: One of the various recruitment assessment tests that can be taken as part of a recruitment process.
• Assessment Package: A collection of one or more Assessments to be completed for a Recruitment.
• Assessio Platform: Our integrated talent management platform.
• Candidate: The individual who will be sent the assessments to complete.
• Integrator: A third party that builds an integration to our platform using the Recruitment API.
• Lens: A job/role profile defining the assessment package, and the competency scores in the results payload.
• Organisation: A client organisation account within Assessio Platform.
• Recruitment: The job context for which candidates are applying—associated with a given Lens.
• Recruitment Module: The module within the platform that provides recruitment functionality for candidate assessments.
• Result: The collection of scores and URLs where additional information can be accessed.
• Score: A value between 0–100 related to the completed assessment package and lens.

To establish an integration utilising the Recruitment API for testing, the following steps need to be completed:

1. Request a sandbox test organisation from Assessio.
   • You will be provided with a sandbox account and an associated provider-key.
2. Obtain integration credentials for authenticating against our API:
   • integrator-secret: A secret used to sign requests from the Integrator to the Assessio platform.
     For details on how this HMAC signature is generated, see Request Signing.

     Note: If required, Assessio can disable this signature requirement in the sandbox environment to simplify initial testing.

   • provider-key: Identifies your Assessio organization. This key must be included in calls to our Assessio-hosted endpoints (e.g., /recruitment/v1/config and /recruitment/v1/assessment-order).

     If multiple organisations are used with the integration, each one is expected to use its own key.

   • Token for Assessio → Integrator Webhook Calls: In order for the Assessio Platform to authenticate when calling your webhook (resultUpdateUrl), you have two options:
     1. Provide an API token (previously referred to as integrator-api-key). We can either generate it and share it with you, or you can provide a token value that you want us to use.
     2. Set up OAuth2 Client Credentials. Contact the Assessio team if you prefer using OAuth2 for securing webhook calls.

Once the Integrator has created and tested the integration on the sandbox environment, the Assessio team can be contacted to exchange production credentials (including production provider-key, integrator-secret, and token credentials) and enable the integration on the production environment.

A high-level overview of how an Integrator typically uses this API:

1. Fetch possible configuration (available lenses and locales) from the /recruitment/v1/config endpoint.
2. Create an assessment order (invite candidates) by calling the /recruitment/v1/assessment-order endpoint with the chosen lens and locale.
3. Receive results when available through the webhook you specify in resultUpdateUrl.

Some requests to our API require an HMAC to be generated from the timestamp combined with the payload. Below is an example in Java:

String encode() throws NoSuchAlgorithmException, InvalidKeyException {
  var timestamp = Instant.now().getEpochSecond();
  var key = "TODO";   // your integrator-secret
  var payload = "{}"; // the raw JSON payload
  var data = timestamp + "." + payload;
  var sha256Hmac = Mac.getInstance("HmacSHA256");
  var secretKey = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
  sha256Hmac.init(secretKey);
  return String.valueOf(Hex.encode(sha256Hmac.doFinal(data.getBytes(StandardCharsets.UTF_8))));
}

The Signature header must include:

• t: The Unix timestamp (in seconds) when the signature was created.
• signature: The HMAC digest of t + "." + (request body).

We allow a timestamp skew of up to 5 minutes (300 seconds). Requests outside that timeframe will be rejected.