Analysis - TMA

Overview

POST
https://api-external.domain.com/api/anonymous/assessment

This document provides detailed information on how to use the Assessment Creation API endpoint. This API allows you to start up a new assessment for a candidate in the system.

Request Body

{
  "ExternalId": "string",
  "AssessmentType": integer,
  "ReturnUrl": "string"
}

Field Descriptions

Field	Type	Required	Description
ExternalId	string	Yes	The unique identifier of the candidate for whom the assessment is to be created. Must match an existing ExternalId in the system.
AssessmentType	integer	Yes	The type of assessment to create. Only 0 (TMA170) and 1 (TMA312) are supported.
ReturnUrl	string	Optional	A URL to which the candidate will be redirected upon completing the assessment. If not provided, a message will prompt the candidate to close the tab.

AssessmentType Options

Value	Description
0	TMA170
1	TMA312

Response

Success Response

Status Code: 201 Created

Response Body

{
  "StatusCode": 201,
  "Message": null,
  "Data": {
    "AnalysisId": "oqvJMOTMBVAAjAzRWW7oAJhB9VuPJi",
    "AssessmentUrl": "{portaldomain}/anonymous/analyse/start/oqvJMOTMBVAAjAzRWW7oAJhB9VuPJi"
  }
}

info

• portaldomain will be determined automatically based on the API key details linked to the portal.

Error Responses

Bad Request

Status Code: 400 Bad Request

Example Response

{
    "error": {
        "code": "NoCandidateFound",
        "message": "No candidate found.",
        "innererror": {}
    }
}

Unauthorized

• Status Code: 401 The provided API key is not valid
• Status Code: 401 Invalid username or password

Additional Information

• All fields are required, except for ReturnUrl, which is optional.
• The ExternalId must correspond to an existing candidate in the system. If the ExternalId does not exist, a 400 Bad Request error will be returned.
• AssessmentType must be either 0 (TMA170) or 1 (TMA312). Other values are not supported and will result in a 400 Bad Request error.
• If ReturnUrl is not provided, upon completion of the assessment, the candidate will receive a message prompting them to close their browser tab or window.

Webhook Support (Optional)

We support webhook notifications for assessment completion events. This feature is optional and can be configured as per your requirements.

How Webhooks Work

• Event Triggered: When a candidate completes an assessment.
• HTTP Method: POST
• Request URL: The WebhookUrl you provide in the API request.
• Authentication: Optional. Can be Anonymous or Basic Authentication.
• Retry Policy: Fire-and-forget. The system will not retry the webhook call in case of failure (downtime, unreachable URL, etc.).

Webhook Request Body

{
  "Analysis_Id": "string",
  "External_Id": "string"
}

Field Descriptions

Field	Type	Description
Analysis_Id	string	Required. The assessment token. This is the last part of the AssessmentUrl provided in the success response.
External_Id	string	Required. The unique identifier you provided for the candidate (ExternalId) when creating the assessment.

Configuring Webhooks

Anonymous Webhook

• Provide WebhookUrl to your endpoint URL.
• The system will send a POST request without any authentication headers.

Basic Authentication Webhook

• Provide WebhookUrl to your endpoint URL.
• Provide WebhookUsername and WebhookPassword.
• The system will send a POST request with an Authorization header containing your credentials encoded in Base64.

Important Notes

• One-Time Attempt: The webhook is a one-time attempt. If the webhook endpoint is unreachable or returns an error, the system will not retry the request.
• Security: Ensure that your webhook endpoint is secured appropriately, especially if using Basic Authentication. Only Basic Authentication and Anonymous access are supported at this time.
• Payload Validation: Your webhook endpoint must be prepared to receive the required JSON payload and handle it accordingly.

Examples

Example Request

POST /api/anonymous/assessment HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Basic am9objpzdXBlcnNlY3JldA==
api-key: your_api_key_here

{
  "ExternalId": "john.williams",
  "AssessmentType": 0,
  "ReturnUrl": "https://example.com/assessment-complete"
}

Example Success Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "StatusCode": 201,
  "Message": null,
  "Data": {
    "AssessmentUrl": "https://portal.example.com/anonymous/analyse/start/oqvJMOTMBVAAjAzRWW7oAJhB9VuPJi"
  }
}

Example Error Response (Invalid ExternalId)

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "InvalidExternalId",
    "message": "The provided ExternalId does not exist",
    "innererror": {}
  }
}

Example Webhook Request (Basic Authentication)

POST /webhook/assessment-complete HTTP/1.1
Host: yourapp.com
Content-Type: application/json
Authorization: Basic d2ViaG9va1VzZXI6d2ViaG9va1Bhc3M=

{
  "Analysis_Id": "oqvJMOTMBVAAjAzRWW7oAJhB9VuPJi",
  "External_Id": "john.williams"
}