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

• Submit assessment orders for employees to complete assessments. The result of submitting an assessment order is a link to the assessment.
• Subscribing webhooks for receiving updates regarding requested assessments.

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.

• Assessio Platform: Our integrated talent management platform.
• Assessment: One of the various assessment tests that can be taken in Assessio Platform.
• Employee: The individual who will be taking the assessment(s).
• Integrator: A third party that builds an integration to our platform using the Development API.
• Organisation: A client organisation account within Assessio Platform.

To establish an integration utilising the Development 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. /development/v1/assessment-link-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. Create assessment link (receive link to assessment and register for assessment updates) by calling the /development/v1/assessment-link-order endpoint.
2. Receive assessment result updates (receive information about assessment submissions either when employee completes it or agrees to use existing results) on the/<:integrator-defined-webhook> endpoint.

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.

Endpoints hosted by Assessio Platform.

Endpoint hosted by the Integrator.