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

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 Add PBTs.
   
3. Using  POST  API Create 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  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  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/Test Links

At Mettl, to allow a candidate to take an assessment/test, you need to create a schedule/test link. Using   POST  API Create Schedule for a particular Assessment , you can create multiple schedules/test links 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/test link allows a candidate to attempt a test only once. Any number of candidates may be allowed to the test through one schedule/test link. Please refer this article to understand how to create a schedule from your account dashboard.

As a suggestion, you can name the schedules/test links 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. 

Live updation of scores and reports using a Webhook

You may configure Webhooks and set their callback URLs on the following JSON properties of each schedule/test link to receive live notifications and results on your application. To configure these:

1. At the time of schedule/test link creation using  POST  API Create Schedule for a particular Assessment.
   
2. For schedules/test links that were created earlier using  POST  API Edit Schedule.
   

These properties can be set in the  sc  JSON in the above APIs. 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’s test is allowed to resume by an Admin after logging in to their mettl account.
   

To secure these notifications from Mettl:

1. While creating or editing a schedule/test link, supply an additional parameter testNotificationBasicAuthHeader with value as base64encoded(username:password)
   
2. In case IP Whitelisting is required, IP addresses can be found here.
   

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.
   For the full list of values, please refer this article.
   
   
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.
   
   
3. Recommendation(s) and Response Style - In reports that contain these elements, the recommendation(s) and response style are also included in the webhook response.  

On demand Results

If required, you may use   GET    APIs  Get Results of All Candidates in Schedule , Get Result of Candidate in Schedule or  Get All Results of Candidate in Account   for on demand results. 

 GET   API  Get All Results of Candidate in Account   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  Register Candidates in Schedule . T his should be in sync with the information collected at the time of candidate signup on the ATS/LMS.

Starting the Test

Using   POST    API  Register Candidates in Schedule , 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). This   POST  API  needs to be supplied with an access-key which uniquely identifies a schedule/test link. (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

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. 
   

Sample Flowchart and Sequence Flow

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.