8. Create Assessment
Definition
This POST API is used to create an Assessment.
*PDF documentation reference - Section 4.1 Create an Assessment
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 . |
| assessments | This is a JSON string containing the details of the assessment to be created. The format for the JSON is given below |
POST request syntax with mandatory parameters:
https://api.mettl.com/v2/assessments?ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}&assessments={Assessments-JSON}
JSON ( assessments )
Format of JSON string to be passed in query parameter assessments can be found in the table below. This JSON describes the details of the assessments to be created.
Note: In the assessments JSON, a property can become mandatory or optional depending on other properties, but properties highlighted with the color yellow are always mandatory.
| Property | Sub Property | Sub Property | Description |
| name | Name of the assessment. This string is always mandatory and has to be unique for each assessment in your account. | ||
| duration | Duration of the assessment in minutes. This integer is only mandatory when each section does not have its own duration and should be more than 0. | ||
| instructions | Instructions shown before and during the assessment. This string is optional and accepts HTML tags as well with the default value being blank. | ||
| allowCopyPaste | Determines whether copy and paste is allowed in the assessment. This boolean is optional and is false by default. | ||
| exitRedirectionURL | Link or URL to redirect the test-taker after assessment finishes. This string is optional and is blank by default. | ||
| showReportToCandidateOnExit | Determines whether the report is shown to the test-taker after assessment finishes. This boolean is optional and is false by default. | ||
| onScreenCalculator | Determines whether an on-screen scientific calculator is available to test-taker during the assessment. This boolean is optional and is false by default. | ||
| sections | Sections in the assessment. This list of nested JSON(s) is always mandatory. | ||
| ↳ | name | Name of a section in the assessment. This string is always mandatory. | |
| ↳ | duration | Duration of a section in the assessment in minutes. This integer is only mandatory when the assessment does not have its own duration and should be more than 0. | |
| ↳ | instructions | Instructions of a section shown during the assessment. This string is optional and is blank by default. | |
| ↳ | allQuestionsMandatory | Determines whether all questions in a section are mandatory. This boolean is optional and is false by default. | |
| ↳ | randomizeQuestions | Determines whether questions will be randomly selected from the skills in a section. This boolean is optional and is false by default. | |
| ↳ | skills | Skills to be added to a section of the assessment. This list of nested JSON(s) is always mandatory. | |
| ↳ | name | Name of the skill to be added to a section. This string is always mandatory and only accepts the names of the skills already added in your question bank. | |
| ↳ | level | Difficulty level of questions in the skill to be added to a section. This string is always mandatory and only accepts the levels available in the skill, i.e., either "easy", "medium" or "difficult". | |
| ↳ | questionCount | Number of questions in the skill to be added to a section. This integer is always mandatory and should be more than 0 but less than or equal to the number of questions with the given difficulty level and question types in the added skill . | |
| ↳ | questionPooling | Determines whether questions will be randomly selected from the skill. This boolean is optional and is false by default. | |
| ↳ | questionType | Type of questions in the skill to be added to a section. This string is optional and only accepts the question types available in the skill, i.e., either "AllType", "MCQ", "MCA", "SHORT_ANSWER", "FITB", "LONG_ANSWER", "CODE", "SQL", "CS", "CP", "FES", "TS" or "FU" with the default value being "AllType". | |
| ↳ | correctGrade | Marks awarded for correctly answering a question. This floating point decimal number is always mandatory and should be more than 0. | |
| ↳ | incorrectGrade | Marks deducted for incorrectly answering a question. This floating point decimal number is optional and should be less than or equal to 0 with the default value being 0. |
For easier readability, the sample assessments JSONs below have pretty formatting, but in your actual request and for signature generation, they should be ideally minified.
1) Sample assessments JSON with only mandatory properties:
{
"name": "Assessment Name",
"duration": 10,
"sections": [
{
"name": "Section Name",
"skills": [
{
"name": "Skill Name",
"level": "easy",
"questionCount": 10,
"correctGrade": 1
}
]
}
]
}
2) Sample assessments JSON with all properties:
{
"name": "Assessment Name",
"duration": 10,
"instructions": "Instructions for attempting the assessment",
"allowCopyPaste": true,
"exitRedirectionURL": "www.samplewebsite.com",
"showReportToCandidateOnExit": true,
"onScreenCalculator": true,
"sections": [
{
"name": "Section Name",
"duration": 10,
"instructions": "Instructions for attempting the section",
"allQuestionsMandatory": true,
"randomizeQuestions": true,
"skills": [
{
"name": "Skill Name",
"level": "easy",
"questionCount": 10,
"questionPooling": true,
"questionType": "MCQ",
"correctGrade": 1,
"incorrectGrade": -0.25
}
]
}
]
}
Example
Request without Signature
a. POST request URL, with queries ak , ts and assessments (URL encoded) but without asgn (Signature)
https://api.mettl.com/v2/assessments?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&assessments=%7B%22name%22%3A%22Assessment%20Name%22%2C%22duration%22%3A10%2C%22sections%22%3A%5B%7B%22name%22%3A%22Section%20Name%22%2C%22skills%22%3A%5B%7B%22name%22%3A%22Skill%20Name%22%2C%22level%22%3A%22easy%22%2C%22questionCount%22%3A10%2C%22correctGrade%22%3A1%7D%5D%7D%5D%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 , assessments and ts in order, for this example)
String-to-Sign = "POST" + "https://api.mettl.com/v2/assessments" + "\n" + "ab12c345-6789-0123-456d-78e9f0123456" + "\n" + "{"name":"Assessment Name","duration":10,"sections":[{"name":"Section Name","skills":[{"name":"Skill Name","level":"easy","questionCount":10,"correctGrade":1}]}]}" + "\n" + "1635976200"
c. Output of the Sting-to-Sign created above
ab12c345-6789-0123-456d-78e9f0123456
{"name":"Assessment Name","duration":10,"sections":[{"name":"Section Name","skills":[{"name":"Skill Name","level":"easy","questionCount":10,"correctGrade":1}]}]}
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)
Au9naXK5Da%2BSjQLkcLSHtMD8iJy9QzIXKB2oSmV8RrQ%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 , assessments (URL encoded) and asgn (URL Encoded)
https://api.mettl.com/v2/assessments?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&assessments=%7B%22name%22%3A%22Assessment%20Name%22%2C%22duration%22%3A10%2C%22sections%22%3A%5B%7B%22name%22%3A%22Section%20Name%22%2C%22skills%22%3A%5B%7B%22name%22%3A%22Skill%20Name%22%2C%22level%22%3A%22easy%22%2C%22questionCount%22%3A10%2C%22correctGrade%22%3A1%7D%5D%7D%5D%7D&asgn=Au9naXK5Da%2BSjQLkcLSHtMD8iJy9QzIXKB2oSmV8RrQ%3D
Response
Upon making a successful request, if there are no errors, you will receive a JSON in the given format
{
"status": "SUCCESS",
"assessmentId": 999999
}