9. Edit Assessment Settings
Definition
This POST API is used to edit the assessment level settings of a particular assessment.
*PDF documentation reference - Section 4.7 Edit Assessment settings for a particular Assessment
Endpoints
where, assessment-id is the unique Id of the assessment you want to edit.
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 . |
| as | This is a JSON string containing the assessment level details of the assessment to be edited. The format for the JSON is given below |
GET request syntax with mandatory parameters:
https://api.mettl.com/v2/assessments?ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}&as={as-JSON}
JSON ( as )
Format of JSON string to be passed in query parameter as can be found in the table below. This JSON describes the details of the assessments to be edited.
Note: There are no mandatory properties for as JSON below.
| Property | Description |
| instructions | Instructions shown before and during the assessment. This value is a string and also accepts HTML tags |
| allowCopyPaste | Determines whether copy and paste is allowed in the assessment. This value is a boolean. |
| exitRedirectionURL | Link or URL to redirect the test-taker after assessment finishes. This value is a string. |
| showReportToCandidate | Determines whether the report is shown to the test-taker after assessment finishes. This value is a boolean. |
| onScreenCalculator | Determines whether an on-screen scientific calculator is available to test-taker during the assessment. This value is a boolean. |
For easier readability, the sample as JSONs below has pretty formatting, but in your actual request and for signature generation, they should be ideally minified.
Sample as JSON with all properties:
{
"instructions": "Instructions for attempting the assessment",
"allowCopyPaste": true,
"exitRedirectionURL": "www.samplewebsite.com",
"showReportToCandidateOnExit": true,
"onScreenCalculator": true,
}
Example
Request without Signature
a. POST request URL, with queries ak , ts and as (URL encoded) but without asgn (Signature)
https://api.mettl.com/v2/assessments/999999/settings/edit?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&as=%7B%22instructions%22%3A%22Instructions%20for%20attempting%20the%20assessment%22%7D
b. Creating a String-to-Sign, calculated with Method + Endpoint + Values of query parameters, in new lines and in ascending order of the parameter name (i.e., the new line characters "\n" followed by values of ak , as and ts in order, for this example)
String-to-Sign = "POST" + "https://api.mettl.com/v2/assessments/999999/settings/edit" + "\n" + "ab12c345-6789-0123-456d-78e9f0123456" + "\n" + "{"instructions":"Instructions for attempting the assessment"}" + "\n" + "1635976200"
c. Output of the Sting-to-Sign created above
ab12c345-6789-0123-456d-78e9f0123456
{"instructions":"Instructions for attempting the assessment"}
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)
AZb8qtSQqSbGgVMalQgwJuY0aEItb58SHIMUITWdepc%3D
Read more about the above Signature Generation Process in API Authentication and Signature Generation
Request with Signature
f. Final POST request URL with queries ak , ts , as (URL encoded) and asgn (URL Encoded)
https://api.mettl.com/v2/assessments/999999/settings/edit?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&as=%7B%22instructions%22%3A%22Instructions%20for%20attempting%20the%20assessment%22%7D&asgn=AZb8qtSQqSbGgVMalQgwJuY0aEItb58SHIMUITWdepc%3D
Response
Upon making a successful request, if there are no errors, you will receive a JSON in the given format
{
"status": "SUCCESS",
"assessment": {
"id": 999999,
"duration": 10,
"testsTaken": 0,
"name": "Assessment Name",
"instructions": "Instructions for attempting the assessment",
"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 Name</td><td>10</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": null,
"customAssessmentName": null,
"showReportToCandidateOnExit": false,
"onScreenCalculator": false,
"fixedSectionOrder": false,
"createdAt": "Mon, 31 Jan 2022 08:58:49 GMT",
"maxMarks": 10.0,
"markingScheme": "FIXED",
"assessmentType": "REGULAR",
"enableQRUpload": false,
"sections": [
{
"name": "Section Name",
"instructions": "",
"duration": 0,
"isTimed": false,
"order": 1,
"randomizeQuestions": false,
"randomizeOptions": false,
"allQuestionsMandatory": false,
"isMinimumQuestion": false,
"minimumQuestion": 0,
"skills": [
{
"name": "Skill Name",
"level": "EASY",
"questionCount": 10,
"source": "Custom",
"questionType": "AllType",
"duration": 0,
"correctGrade": 1.0,
"incorrectGrade": 0.0,
"questionPooling": true
}
]
}
],
"assessmentTags": [],
"registrationFields": [
{
"name": "Email Address",
"type": "TextBox",
"required": true,
"validate": false
},
{
"name": "First Name",
"type": "TextBox",
"required": true,
"validate": false
}
],
"assessmentPerformanceCategory": null,
"apiAssessmentLanguage": {
"value": 1,
"language": "English",
"direction": "ltr",
"langColumn": "English_Text",
"assessmentId": null
},
"assessmentAdditionalInfo": {
"versionId": -1,
"assessmentRecommendations": null
}
}
}