Mercer | Mettl API Integration Flow

API Integration Flow

Sample API Integration Flow Diagram

The following article details a sample integration flow to help you get started. To read more about each of the APIs mentioned below, request you to refer to our API Documentation

Admin Side Flow

Assessment Creation

You can add/create assessments by:
  1. Logging in to mettl.com i.e, through your dashboard - You can add prebuilt tests (PBTs) to your account from our Test Library or create a custom assessment.
  2. Using POST API 3.2 Add list of PBTs to Account.
  3. Using POST API 4.1 Create an assessment. This option can only be used to create assessments at runtime with your questions only imported onto Mettl by you or your team. (Click here to read how to import your questions)

Mapping Jobs/Courses on your ATS/LMS to Mettl Assessments

GET API 4.2 Get all Assessments can be used to retrieve all assessments in your Mettl account to proceed with mapping them with jobs/courses on your system. Each assessment has a unique identifier called assessment ID. 
At this step, you can also define a passing criteria (if any) on your ATS/LMS for each assessment mapped to a job/course.

Candidate Experience - Redirection after Finishing Test

Using POST API 4.7 Edit Assessment settings for a particular Assessment, you can set a URL to which candidate should be redirected to, after clicking on ‘Finish Test’ on the Mettl test window. In this API, please refer to the parameter: “exitRedirectionURL”.

ATS/LMS Back-End Flow

Creation of Schedules/Events

At Mettl, to allow a candidate to take an assessment/test, you need to create schedule(s). Using POST API 5.1 Create Schedule for a particular Assessment, you can create multiple schedules for each assessment depending on:
  1. The number of attempts allowed for a candidate.
  2. If different sets of candidates need to be administered the assessment with a unique set of security settings. 
A schedule/event allows a candidate to attempt a test only once. Any number of candidates may be allowed to the test through one schedule/event. Please refer this article to understand how to create a schedule from your account dashboard.
As a suggestion, you can name the schedules as 1st attempt, 2nd attempt and so on. Each schedule is uniquely identified by its access-key. When/If a candidate is eligible to take the 2nd attempt of the same test, the access-key of the second schedule can be sent and so on. 

Updation of scores and reports using a JSON Listener

You may configure JSON listeners and set their URLs on the following callbackURLs of each schedule/access-key to update the ATS/LMS. To configure these:
  1. At the time of schedule creation via API itself using POST API 5.1 Create Schedule for a particular Assessment, these parameters can be set in the same call itself.
  2. For schedules that were created earlier, either via the dashboard or via API, this can be done using POST API 5.2 Edit Schedule for a particular Assessment.
Mettl will POST JSON data on these URLs for the respective candidate actions:
  1. testStartNotificationURL: When a candidate’s test starts
  2. testFinishNotificationURL: When a candidate’s test ends
  3. testGradedNotificationURL: When a candidate’s test result gets generated
  4. testResumeEnabledForExpiredTestURL: When an expired candidate is allowed to resume by an Admin after logging in to the mettl.com account.
To receive these notifications from Mettl:
  1. Whitelist the following IP address: 13.126.94.65
  2. In case basic authentication is required, while creating/editing a schedule, supply an additional parameter testNotificationBasicAuthHeader with value as base64encoded(username:password)
In addition to the detailed scores and the HTML report link, the JSON data POSTed on the testGradedNotificationURL also contains:
  1. completionMode – This will help the Admin understand if the candidate:
    1. Successfully completed the test – By clicking on Finish test, or because the timer counted down to zero.
    2. Navigated away more times than allowed and the test was stopped by Mettl
    3. Got disconnected due to power/internet disconnection – this indicates to the Admin that the test maybe incomplete. In such a case, you may use this input to display an appropriate message to the logged in user on your system.

  2. candidateCredibilityIndex – Possible values are High, Medium or Low
    Low credibility means candidate is more likely to have cheated and that the Admin should review the test log/red flags. Click here to know more about this feature.

On demand Results

If required, you may use GET API 6.2, 6.3 or 7 for on demand results. 
GET API 7 Get all details for a particular candidate may be used to build a candidate's profile. This will return information about all tests taken by a candidate. 
For Psychometric assessment reports (link to sample), do not consider any of the scores in the JSON response. By including the following non-mandatory arguments, you may also fetch:
  1. 'Recommendation' values - "ir":'{"recommendation":true}'
  2. 'Response Style' value - rs = true;
For competency level data, please reach out to us for a consultation.

Candidate Flow

At Mettl, candidates are identified uniquely using their email ID.

Please set the candidate registration fields as desired in the account level settings in your Mettl.com account in the very beginning as this is required while using POST API 6.1.2 Register candidate for a test. This should be in sync with the information collected at the time of candidate signup on the ATS/LMS.

Starting the Test

Using POST API 6.1.2 Register candidate for a test, you can give a single-sign-on experience to the candidate i.e. the candidate doesn't have to fill in any details, test starts directly). The POST API 6.1.2 needs to be supplied with an access-key/schedule. (See ATS/LMS Back-end flow)
When this API is used a candidate specific encrypted URL is generated which can be used by the candidate only once. (Hence, there is no possibility of misuse)
This candidate-specific-encrypted link can be:
  1. Sent to the candidate over email.
  2. Displayed to the candidate on the LMS/ATS. Optionally, at the candidate’s selected slot time, the ‘Take Test’ button can be enabled. 
For an L&D scenario, to enable SAML SSO for your candidates/employees, please refer this article.

Making Report available on Candidate/Admin dashboard

The JSON data POSTed on the testGradedNotificationURL also contains the candidate's HTML report URL. As per the requirement, this can be shared with candidate on his/her profile or displayed to an Admin on the ATS/LMS.

Resuming an Expired Test

In case a candidate's test is interrupted for some reason, the candidate may refresh the test link and continue the test from the point of disruption within 30mins.
If the candidate couldn't do this for some reason, Mettl grades the candidates responses and sends results to ATS/LMS:
  1. In the data posted on the testGradeNotificationUrl the value of the parameter finish_mode will be TestExpired.
  2. In case the candidate's result is accessed on demand using API 6.2 or 6.3 or 7, the value of completionMode will be Expired
In such cases, you may display a notification to the candidate that they may contact ATS/LMS Admin to resume the test. Only an Admin who can login to the Mettl.com account may resume such a test. When this is done, Mettl sends a notification on the testResumeEnabledForExpiredTestURL

You can use this notification to re-activate the Take test button on the candidate's profile or send an email to the candidate.

Sample Flowchart and Sequence Flow

The following documents will help you understand how to understand how to use our APIs to integrate your system with our assessment platform:
  1. Flowchart: To understand the flow of candidates and assessment between Mettl and your application
  2. Sequential Explanations: A detailed explanation of API calls and necessary parameters needed for the flow of data and how to store it.