Guide to Mercer | Mettl Examine APIs

Guide to Mercer | Mettl Examine APIs

Introduction

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

Prerequisites

You should be familiar with Mettl Examine Dashboard's terminologies and functioning. It is highly recommended that you know the following operations on Mettl Dashboard before using these APIs. The relevant support articles can be found here on our support website –  
It is assumed you have already created an Mettl account and received your public API Key and private API Key. In case you don't know your API keys, please contact your Mettl Account/Sales manager for API keys to your Mettl account or send an email to mettl-delivery@mercer.com. To create a new account, see Creating a Mettl Account.

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

Examine Platform Structure

In order to fully comprehend Mettl Examine APIs you need to understand the structure of the Mettl Examine Platform. In your Mettl Account, you can add as many Assessments as you want, be it a Pre-built Assessment from our Test Library or a Custom Assessment made by you. But for a test taker to be able to access and take an Assessment, you need to create and share a Test Link/ Schedule with the specific Access and Security settings.

Under each Assessment, you can create multiple Test Links/ Schedules, and under each Test Link/ Schedule, each test taker with a unique email id can give one attempt as shown in the following chart.


Assessments

Assessments refers to any pre built or custom built tests which have added to your account. Mercer | Mettl's Examine Platform supports a multitude of assessments including but not limited to Coding Simulators, Psychometric and Speech Evaluations,  Aptitude Tests etc. Any Assessment added to your account can be seen under the My Tests tab in your dashboard as shown below.



Schedules

Schedules are instances of Assessments with specific Access and Security Settings. On the Mettl Examine Platform a Schedule is known as a Test Link and each Schedule has its own Access Key which can be used to uniquely identify a Schedule within a Mettl Account.

Schedules can be used to group, control and identify test takers under a single link, and can be mapped to testing events (such as a Campus Hiring Drive on a specific date) or individual attempts (in case where multiple attempts are required) by using the Schedule/ Test Link name.


Opening Schedule(s)


List of Schedules


Schedule Settings


APIs and Integration Flow

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

Account APIs

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

PBT APIs

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

Assessment APIs

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

Schedule APIs

10. Get All Schedules in Assessment API - Fetches details of all schedules for an assessment
11. Get All Schedules in Account API - Fetches details of all schedules in your account 
12. Get Schedule API - Fetches details of a particular schedule in your account
13. Create Schedule API* - Creates a new schedule for a particular assessment. Can also be used to set up live notifications for test events (Such as getting candidate's results as soon as they are generated on callback url) 
14. Edit Schedule API - Edits a existing schedule for a particular assessment. Same functionality as above 
15. Register Candidates in Schedule API* - Registers candidates in a schedule and generates an encrypted test link for each candidate

Result APIs

16. Get Status/Results of All Candidates in Schedule API - Fetches details about all registered candidates test status (started, active, idle, expired, completed) and results (score, reports, proctoring details, etc.) in a particular schedule.
17. Get Status/Result of Candidate in Schedule API* - Fetches details about a single registered candidate's test status and result in a particular schedule.
18. Get All Status/Results of Candidate API - Fetches all details about a single registered candidate's test status and results in all schedules in your account.
19. Delete Result of Candidate in Schedule API - Deletes details about a single registered candidate's test status and result in a particular schedule, if the test has been “completed” or is “Expired”. The tests “in-progress” will remain unaffected. 

Sample Integration

Depending on your requirements you can built a standard integration using only 3-4 APIs listed above (important ones star marked above). Check out our API Integration workflow.

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 query parameters which have been highlighted. Using this highlighting, we can easily show different query parameters and their values in examples, formats and regular text. 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  ,etc. - Optional query parameters depending on the API
which can often be found in 
Formats used in API or Signature Generation pages which will be highlighted like this with pale green color
Examples used in API or Signature Generation pages which will be highlighted like this with light blue color

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.comin 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 wanna test out our APIs without writing any code, you can check out our Examine API Demo portal.