Mettl's API Documentation

API Documentation

Welcome to Mercer | Mettl Examine APIs. This page details the REST based APIs using which you can interact and integrate with Mercer | Mettl Examine application.

Prerequisites

In order to fully comprehend our Examine REST APIs, you should be familiar with Mettl Examine Dashboard's terminologies and functioning. It is highly recommended that you know the following operations on your Dashboard before using these APIs.
  1. How to create Assessments
  2. How to schedule Assessments and Invite Candidates 
  3. How to view Results of a particular assessment 
  4. How to manage candidates and batches 
  5. Take a test on Mettl.com to see Test Taker’s experience
To get your API keys, please contact your Mettl Account/Sales manager for the API keys to your Mettl account or send an email to mettl-delivery@mercer.com.

Examine Platform Structure

About Schedules

On the Mettl Examine Platform a Schedule is known as a Test Link. Schedules are instances of assessments in your account with specific Access and Proctoring Settings.

For a candidate to be able to access and take an assessment on Mettl, you need to create and share a schedule/ test link of that assessment. Each schedule has its own Access Key which can be used to uniquely identify a schedule/ test link for making API call.

Since a unique email Id can only take a test once in a schedule/ test link, they can be used to group, control and identify test takers under a single object. These can be mapped to testing events (such as a Job Requisition or Course) or individual attempts (in case where multiple attempts are required) in your system.


List of Assessments


Opening Schedule(s) in an Assessment


List of Schedules in an Assessment


Schedule Settings

Sample Integration

Depending on your requirements you can built a standard integration using only 3-4 APIs listed below (important ones are star marked) along with our webhooks for receiving live test results. Check out our sample API Integration workflow.

APIs

You can find the list of our Examine APIs below and along with their functionality

Account APIs

1.  GET  Get Account Info - Fetches your account information (i.e. Name, Email, Account Type etc.)
2.  POST  Update Logo - Uploads a logo in your account to customize the test experience of your candidates
3.  POST  Update White Label - Updates white labelling settings in your account to customize the test experience of your candidates

PBT APIs

4.  GET  Get All PBTs - Retrieves list of all Pre Built Tests available with Mercer | Mettl
5.  POST  Add PBTs -  Adds list of Pre Built Tests to the assessments in your Account

Assessment APIs

6.  GET  Get All Assessments * - Fetches details of all assessments added in your account
7.  GET  Get Assessment - Fetches details of a single assessment in your account
8.  POST  Create Assessment - Creates a new assessment
9.  POST  Edit Assessment - Edits assessment settings 

Schedule APIs

10.  GET  Get All Schedules in Assessment - Fetches details of all schedules/ test links in an assessment
11.  GET  Get All Schedules in Account - Fetches details of all schedules/ test links in your account 
12.  GET  Get Schedule - Fetches details of a particular schedule/ test link in your account
13.  POST  Create Schedule * - Creates a new schedule/ test link for a particular assessment. Can also be used to send the start test email from a Mercer | Mettl email Id as well as set up webhooks to receive live notifications for test results.  
14.  POST  Edit Schedule * - Edits a existing schedule/ test link for a particular assessment. Same functionality as above 
15.  POST  Register Candidates in Schedule * - Registers candidates in a schedule/ test link and generates an encrypted test link for each candidate which can be used to populate a start test button on your app or in an email generated from your system.

Result APIs

16.  GET  Get Results of All Candidates in Schedule - Fetches details of all candidates test status (started, active, idle, expired, completed) and results (score, reports, proctoring details, etc.) in a particular schedule/ test link.
17.  GET  Get Result of Candidate in Schedule - Fetches details of a single candidate's test status or result in a particular schedule/ test link.
18.  GET  Get All Results of Candidate in Account - Fetches details of a single candidate's test status and results from all schedules/ test links in your account.
19.  DELETE  Delete Result of Candidate in Schedule - Deletes details of a single candidate's test status or result in a particular schedule/ test link.

API Authentication

Our Examine APIs can be accessed using a pair of Public and Private API Keys. When accessing Mettl Examine platform using a REST API request, you must always provide 3 mandatory query parameters, i.e.,   ak  (Public API Key) ,  ts  (Current UNIX timestamp) and  asgn  (HMAC-SHA based Signature hashed using the Private API Key), so that the request can be authenticated.

You can read about the signature generation process for the  asgn  query parameter in API Authentication and Signature Generation.

We also have sample code snippets in C#, Java, Node.js, PHP and Python for some of our APIs, which you can use to understand our authentication process in API Signature Generation Code Samples.

Webhooks

Schedule Webhooks

Our Examine APIs have support for configuring webhooks for sending live test and result notifications at the schedule/ test link level to your system. You can also get live notifications of following events by setting the callback URL in the schedule/ test link properties using either  POST  Create Schedule API or  POST  Edit Schedule API.
  1. When a candidate’s test starts (testStartNotificationUrl)
  2. When a candidate’s test ends (testFinishNotificationUrl)
  3. When a candidate’s test result gets generated (testGradedNotificationUrl)
  4. When a candidate is allowed to resume their expired test (testResumeEnabledForExpiredTestURL)

Webhook Delivery

Your webhook endpoint URL should listen for POST API calls from Mercer | Mettl and respond with a 200 HTTP status code after receiving a webhook request in order for Mercer | Mettl to consider the notification was successfully delivered.

Mercer | Mettl attempts to deliver the webhook three times. If a 200 response is received after any attempt, then Mercer | Mettl considers the notification was successfully delivered. However, if Mercer | Mettl does not receive a 200 response after three attempts, then no further webhooks for that event will be sent.

Webhook Authentication

Basic Authentication

You can also receive Basic Authentication in the webhook notification's header by using the "testNotificationBasicAuthHeader" in the  sc  JSON of either  POST  Create Schedule API or  POST  Edit Schedule API. On providing the value for "testNotificationBasicAuthHeader" in the format base64encoded(username:password), you will receive the following additional authorization headers.
authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
php-auth-user: username
php-auth-pw: password

IP addresses

We strongly recommend that you use Basic Authentication instead of creating an white list of IP addresses because Mercer | Mettl may update the IP ranges used at any time. If you must create an allow list by IP Address, Examine API uses the following to send event notifications:
  1. mettl.com (India server): 15.207.201.179
  2. mercermettl.eu (Europe server):
    1. current - 52.31.72.166
    2. post migration, Jan 2023 - 2.58.180.251
  3. mercermettl.com (China server): 69.230.223.219

Limitations

Please note that the following activities cannot be done through APIs and need to be done on Mettl website – 
  1. Taking test (i.e. candidates will attempt the test on Mettl window only, however, they can choose and start test from client’s portal)
  2. Candidate bank management
  3. Candidate registration field management
  4. Question creation

Color Guide

In our online documentation, you will often run into keywords and parameters which have been highlighted. Using this highlighting, you can easily identify different query parameters and their values in examples, formats and other explanation. This includes
  1.  GET  ,  POST  ,  DELETE  - API request methods
  2.  ak  ,  ts  ,  asgn  - Authentication query parameters for all APIs. For more information refer Authentication and Signature Generation 
  3.  sc  ,  rd  , etc. - Other mandatory query parameters depending on the API
  4.  limit  ,  sort  ,  offset  , etc. - Optional query parameters depending on the API
along with the above, you can also find 
Request Formats will be enclosed like this in pale green color box
Request Examples will be enclosed like this in light blue color box

Host Servers

You can access the Examine APIs using the host URL "https://api.mettl.com" which uses our primary domain mettl.com (same as your Examine dashboard URL), which is hosted in India. But if you are using our platform via the EU servers which use mercermettl.eu, you would need to access our APIs using the host URL "https://api.mercermettl.eu" instead of "https://api.mettl.com" in all the API endpoints. Similarly if you are using our platform via the China servers on mercermettl.com, you would need to access our APIs using China's host URL "https://api.mercermettl.com" instead of "https://api.mettl.com".

API Demo

If you want to test out our APIs without writing any code, you can check out our Examine API Demo portal.