6. Get All Assessments

6. Get All Assessments

Definition

This  GET  API is used to fetch the details of all assessments in your account (such as assessment name, id, duration, tests taken, max marks, candidate registration fields, sectional info, etc.).
      *PDF documentation reference - Section 4.2 Get all Assessments

Remarks

Using this API you can fetch the list of assessments and their details in your account along with their Assessment Ids which can be used uniquely identify any Assessment in your account and is used in other API calls such as Create Schedule API , Get Assessment API or Get All Schedules in Assessment API.

This API is also used in the first step of our sample API Integration Flow, where the list of all assessments can be fetched by a user in your system to be mapped to a stage in a job, course or any activity. 

Pagination

This API has support for pagination and uses the  offset  query parameter to cycle through the full list of Assessments. Any optional parameters (aside from  offset used for the first request will also be reused for generating the the next and previous URLs in pagination response.

Query Parameters

In our REST APIs, Query Parameters have to be URL encoded as the data is being transmitted in the request URL. This is especially important for the  asgn  parameter and any parameters with JSON as they always contain characters that need to be URL encoded. Since  ak  and  ts   parameters don't contain any characters that need to be URL encoded, URL encoding of these parameters can be skipped.

Mandatory parameters


Query Parameter


Description

ak

This is your Public-API-Key, which Mettl uses to identify your account.

ts

This is the current UNIX or Epoch Timestamp (the number of seconds between 1970-01-01 00:00:00 and current UTC Time). Any current generated Timestamp will be valid for 24 hours only.

asgn

This is a unique Signature which has to be generated for each API request.

The Signature is generated by creating a String-to-Sign and hashing it with your Private-API-Key using  the HMAC-SHA256 (for version v2 and v3) or HMAC-SHA1 (for v1) hashing algorithm with Base-64 and URL encoding.

Read more about the above Signature Generation Process in API Authentication and Signature Generation.


 GET  request syntax with mandatory parameters:
https://api.mettl.com/v2/assessments?ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}      

Optional parameters


Query Parameter


Description

limit

Number of assessments to fetch from your account.

You can input a value from 1 to 100, with the default value being 20.

offset

Returns the list of assessments starting from the offset position.

You can input a value from 0 to 1 less than the total number assessments in your account, with the default value being 0.

sort

Property used to sort the list of assessments.

You can input either createdAt, testTaken or name, with the default value being createdAt.

sort_order

Ascending or Descending order used to sort the list of assessments.

You can input either asc or desc, with the default value being desc.


 GET  request syntax with all parameters:
https://api.mettl.com/v2/assessments?ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}&limit={Limit}&offset={Offset}&sort={Sort}&sort_order={Sort-Order}

Examples

1) Request with only mandatory query parameters
Request without Signature
a.  GET  request URL, with queries  ak  and  ts  but without  asgn  (Signature)
https://api.mettl.com/v2/assessments?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200

b. Creating a String-to-Sign, calculated with Method + Endpoint + Values of query parametersin new lines and in ascending order of the parameter name (i.e., the new line characters "\n" followed by values of  ak  and  ts  in order, for this example)
String-to-Sign = "GET" +  "https://api.mettl.com/v2/assessments"  + "\n" + "ab12c345-6789-0123-456d-78e9f0123456"  + "\n" + "1635976200"
c. Output of the Sting-to-Sign created above
ab12c345-6789-0123-456d-78e9f0123456
1635976200
d. Private-API-Key to sign/hash the above Sting-to-Sign using HMAC-SHA256 (since API version is v2)
zy98x765-4321-0987-654w-32v1u0987654
e. Output of the generated Signature for  asgn  using the Sting-to-Sign and your Private-API-Key, hashed with HMAC-SHA256 (Base-64 and URL Encoded)
MXrtmElCTsZUI%2Bipf1e%2F42pX20t4xL28igQFEZxgjkY%3D
Read more about the above Signature Generation Process in API Authentication and Signature Generation

Request with Signature
f. Final  GET  request URL with queries  ak  ,  ts  and  asgn  (URL Encoded)
https://api.mettl.com/v2/assessments?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&asgn=MXrtmElCTsZUI%2Bipf1e%2F42pX20t4xL28igQFEZxgjkY%3D

2) Request with all query parameters
Request without Signature
a. GET request URL, with queries  ak   ts  ,  limit  ,  offset  ,  sort  and  sort_order  but without  asgn  (Signature)
https://api.mettl.com/v2/assessments?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&limit=10&offset=20&sort=name&sort_order=asc

b. Creating a String-to-Sign, calculated with Method + Endpoint + Values of query parametersin new lines and in ascending order of the parameter name (i.e., the new line characters "\n" followed by values of  ak  ,  limit  ,  offset  ,  sort  ,  sort_order  and  ts  in order, for this example)
String-to-Sign = "GET" +  "https://api.mettl.com/v2/assessments"  + "\n" + "ab12c345-6789-0123-456d-78e9f0123456"  + "\n" + "10" + "\n" + "20" + "\n" + "name" + "\n" + "asc" + "\n" + "1635976200"
c. Output of the Sting-to-Sign created above
ab12c345-6789-0123-456d-78e9f0123456
10
20
name
asc
1635976200
d. Private-API-Key to sign/hash the above Sting-to-Sign using HMAC-SHA256 (since API version is v2)
zy98x765-4321-0987-654w-32v1u0987654
e. Output of the generated Signature for  asgn  using the Sting-to-Sign and your Private-API-Key, hashed with HMAC-SHA256 (Base-64 and URL Encoded)
tt7w%2Bvs2dwAeMDMt5y12jKwBPVRaiEu%2FW%2BMHoMZmWRk%3D
Read more about the above Signature Generation Process in API Authentication and Signature Generation

Request with Signature
f. Final  GET  request URL with queries  ak  ,  ts   limit  ,  offset  ,  sort  ,  sort_order  and  asgn  (URL Encoded)
https://api.mettl.com/v2/assessments?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&limit=10&offset=20&sort=name&sort_order=asc&asgn=tt7w%2Bvs2dwAeMDMt5y12jKwBPVRaiEu%2FW%2BMHoMZmWRk%3D

Response

Upon making a successful request, if there are no errors, you will receive a JSON in the given format
{
"status": "SUCCESS",
"assessments": [
{
"id": 717329,
"duration": 60,
"testsTaken": 0,
"name": "Core Java Developer Assessment",
"instructions": "",
"defaultInstructions": "<h2><b>THINGS TO REMEMBER</b></h2><ul style=\"list-style-type:decimal;margin: 10px 20px;\"><li>Before starting the test, please close all chat windows, screen-saver(s), etc. and make sure that you have a stable internet connection.</li><li>Pressing F5 at any time during the test will cause it to end immediately</li><li>If your computer system shuts down suddenly due to your power supply being disconnected, you can resume the test from the same question that you were attempting earlier. All your previous answers are already saved.</li><li>Your test will open in a new popup window once you press the launch test button. </li><li>When resuming, please start the test as you did before and use the same registration details. </li></ul<div class=\"section-duration\">TEST DETAILS<br /><table class=\"table\"><tr><th>Section Name</th><th>No. of Questions</th><th>Time Limit (Mins)</th></tr></table><b>Total Test Duration:</b> 60  Mins</div>",
"allowCopyPaste": false,
"exitRedirectionURL": "",
"customAssessmentName": "",
"showReportToCandidateOnExit": false,
"onScreenCalculator": false,
"fixedSectionOrder": false,
"createdAt": "Mon, 27 Sep 2021 07:29:36 GMT",
"maxMarks": 0.0,
"markingScheme": "FIXED",
"assessmentType": "PBT",
"enableQRUpload": false,
"sections": [],
"assessmentTags": [],
"registrationFields": [
{
"name": "Email Address",
"type": "TextBox",
"required": true,
"validate": false
},
{
"name": "First Name",
"type": "TextBox",
"required": true,
"validate": false
}
],
"apiAssessmentLanguage": {
"value": 1,
"language": "English",
"direction": "ltr",
"langColumn": "English_Text",
"assessmentId": null
}
},
{
"id": 705385,
"duration": 10,
"testsTaken": 2,
"name": "Demo Assessment",
"instructions": "",
"defaultInstructions": "<h2><b>THINGS TO REMEMBER</b></h2><ul style=\"list-style-type:decimal;margin: 10px 20px;\"><li>Before starting the test, please close all chat windows, screen-saver(s), etc. and make sure that you have a stable internet connection.</li><li>Pressing F5 at any time during the test will cause it to end immediately</li><li>If your computer system shuts down suddenly due to your power supply being disconnected, you can resume the test from the same question that you were attempting earlier. All your previous answers are already saved.</li><li>Your test will open in a new popup window once you press the launch test button. </li><li>When resuming, please start the test as you did before and use the same registration details. </li></ul<div class=\"section-duration\">TEST DETAILS<br /><table class=\"table\"><tr><th>Section Name</th><th>No. of Questions</th><th>Time Limit (Mins)</th></tr><tr><td>Section #1</td><td>2</td><td>Untimed*</td></tr></table>*Untimed: These sections are without any specific time limit. You can answer these sections within the total assessment time limit.<br />i.e Total Time of Untimed Sections = Total Time of Test - Total Time of Timed Sections<br /><b>Total Test Duration:</b> 10  Mins</div>",
"allowCopyPaste": false,
"exitRedirectionURL": "",
"customAssessmentName": "",
"showReportToCandidateOnExit": false,
"onScreenCalculator": false,
"fixedSectionOrder": false,
"createdAt": "Fri, 03 Sep 2021 07:47:43 GMT",
"maxMarks": 2.0,
"markingScheme": "FIXED",
"assessmentType": "REGULAR",
"enableQRUpload": false,
"sections": [
{
"name": "Section #1",
"instructions": "",
"duration": 0,
"isTimed": false,
"order": 1,
"randomizeQuestions": true,
"randomizeOptions": true,
"allQuestionsMandatory": false,
"isMinimumQuestion": false,
"minimumQuestion": 15,
"skills": [
{
"name": "RC",
"level": "EASY",
"questionCount": 2,
"source": "Custom",
"questionType": "AllType",
"duration": 0,
"correctGrade": 1.0,
"incorrectGrade": 0.0,
"questionPooling": true
}
]
}
],
"assessmentTags": [
{
"useCaseName": "Others",
"useCaseSubTags": {}
}
],
"registrationFields": [
{
"name": "Email Address",
"type": "TextBox",
"required": true,
"validate": false
},
{
"name": "First Name",
"type": "TextBox",
"required": true,
"validate": false
}
],
"apiAssessmentLanguage": {
"value": 1,
"language": "English",
"direction": "ltr",
"langColumn": "English_Text",
"assessmentId": null
}
},
{
"id": 703395,
"duration": 25,
"testsTaken": 4,
"name": "Mettl Personality Profiler",
"instructions": "",
"defaultInstructions": "<h2><b>THINGS TO REMEMBER</b></h2><ul style=\"list-style-type:decimal;margin: 10px 20px;\"><li>Before starting the test, please close all chat windows, screen-saver(s), etc. and make sure that you have a stable internet connection.</li><li>Pressing F5 at any time during the test will cause it to end immediately</li><li>If your computer system shuts down suddenly due to your power supply being disconnected, you can resume the test from the same question that you were attempting earlier. All your previous answers are already saved.</li><li>Your test will open in a new popup window once you press the launch test button. </li><li>When resuming, please start the test as you did before and use the same registration details. </li></ul<div class=\"section-duration\">TEST DETAILS<br /><table class=\"table\"><tr><th>Section Name</th><th>No. of Questions</th><th>Time Limit (Mins)</th></tr></table><b>Total Test Duration:</b> 25  Mins</div>",
"allowCopyPaste": false,
"exitRedirectionURL": "",
"customAssessmentName": "",
"showReportToCandidateOnExit": false,
"onScreenCalculator": false,
"fixedSectionOrder": false,
"createdAt": "Tue, 31 Aug 2021 09:20:52 GMT",
"maxMarks": 0.0,
"markingScheme": "FIXED",
"assessmentType": "PBT",
"enableQRUpload": false,
"sections": [],
"assessmentTags": [],
"registrationFields": [
{
"name": "Email Address",
"type": "TextBox",
"required": true,
"validate": false
},
{
"name": "First Name",
"type": "TextBox",
"required": true,
"validate": false
}
],
"apiAssessmentLanguage": {
"value": 1,
"language": "English",
"direction": "ltr",
"langColumn": "English_Text",
"assessmentId": null
}
},
{
"id": 703390,
"duration": 45,
"testsTaken": 1,
"name": "Mettl Personality Map",
"instructions": "",
"defaultInstructions": "<h2><b>THINGS TO REMEMBER</b></h2><ul style=\"list-style-type:decimal;margin: 10px 20px;\"><li>Before starting the test, please close all chat windows, screen-saver(s), etc. and make sure that you have a stable internet connection.</li><li>Pressing F5 at any time during the test will cause it to end immediately</li><li>If your computer system shuts down suddenly due to your power supply being disconnected, you can resume the test from the same question that you were attempting earlier. All your previous answers are already saved.</li><li>Your test will open in a new popup window once you press the launch test button. </li><li>When resuming, please start the test as you did before and use the same registration details. </li></ul<div class=\"section-duration\">TEST DETAILS<br /><table class=\"table\"><tr><th>Section Name</th><th>No. of Questions</th><th>Time Limit (Mins)</th></tr></table><b>Total Test Duration:</b> 45  Mins</div>",
"allowCopyPaste": false,
"exitRedirectionURL": "",
"customAssessmentName": "",
"showReportToCandidateOnExit": false,
"onScreenCalculator": false,
"fixedSectionOrder": false,
"createdAt": "Tue, 31 Aug 2021 09:17:37 GMT",
"maxMarks": 0.0,
"markingScheme": "FIXED",
"assessmentType": "PBT",
"enableQRUpload": false,
"sections": [],
"assessmentTags": [
{
"useCaseName": "Others",
"useCaseSubTags": {}
}
],
"registrationFields": [
{
"name": "Email Address",
"type": "TextBox",
"required": true,
"validate": false
},
{
"name": "First Name",
"type": "TextBox",
"required": true,
"validate": false
}
],
"apiAssessmentLanguage": {
"value": 1,
"language": "English",
"direction": "ltr",
"langColumn": "English_Text",
"assessmentId": null
}
}
],
"paging": {
"previous": null,
"next": null
}
}