16. Get Results of All Candidates in Schedule

16. Get Results of All Candidates in Schedule

Definition

This  GET  API is used to fetch the status and results of all candidates in a schedule/ test link (such as candidate registration fields, test status, proctoring details and test results if the test is finished).

where, access-key is the unique key of the schedule/ test link from which you want to fetch the status and results of all candidates.

You can get an access-key from the test link settings in your dashboard (alphanumeric key at the end of the 'Link to Share') or via API by using Create Schedule API , Get All Schedules in Assessment API or Get All Schedules in Account API.

Pagination

This API has support for pagination and uses the  offset  query parameter to cycle through the full list of candidates in a schedule/ test link. 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

IIn 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/schedules/{access-key}/candidates?ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}      

Optional parameters


Query Parameter


Description

ir

Enables sending recommendation in the results wherever the same is configured for an assessment.

You can input a JSON in the format {"recommendation":true} to enable this recommendation which is disabled by default.

qr

Enables sending responses for essay questions where manual grading is required.

You can input either true or false, with the default value being false.

limit

Number of candidate status and results to fetch from your schedule/ test link.

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

offset

Returns the list of candidate status and results starting from the offset position.

You can input a value from 0 to 1 less than the total number of candidate status and results in your schedule/ test link, with the default value being 0.

sort

Property used to sort the list of candidate status and results.

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

sort_order

Ascending or Descending order used to sort the list of candidate status and results.

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


 GET  request syntax with all parameters:
https://api.mettl.com/v2/schedules/{access-key}/candidates?ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}&ir={Recommendation-JSON}&qr={Boolean}&limit={Limit-Number}&offset={Offset-Number}&sort={Sort-Parameter}&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/schedules/0x0x0x0x0x/candidates?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200

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  and  ts  in order, for this example)
String-to-Sign = "GET" +  "https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates"  + "\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)
vtf9LV80jVBq6bzBGnhQbku%2BqfM%2BiCC5i2Lbxk%2FArUM%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/schedules/0x0x0x0x0x/candidates?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&asgn=vtf9LV80jVBq6bzBGnhQbku%2BqfM%2BiCC5i2Lbxk%2FArUM%3D

2) Request with all query parameters
Request without Signature
a. GET request URL, with queries  ak  ,  ts  ,  ir  (URL encoded) ,  qr  ,  limit  ,  offset  ,  sort  and  sort_order  but without  asgn  (Signature)
https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&ir=%7B%22recommendation%22%3Atrue%7D&qr=true&limit=10&offset=20&sort=name&sort_order=asc

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  ,  ir  ,  limit  ,  offset  ,  qr  ,  sort  ,  sort_order  and  ts  in order, for this example)
String-to-Sign = "GET" +  "https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates"  + "\n" + "ab12c345-6789-0123-456d-78e9f0123456"  + "\n" + "{"recommendation":true}" + "\n" + "10" + "\n" + "20" + "\n" + "true" + "\n" + "name" + "\n" + "asc" + "\n" + "1635976200"
c. Output of the Sting-to-Sign created above
ab12c345-6789-0123-456d-78e9f0123456
{"recommendation":true}
10
20
true
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)
BCPevoXzusbBGiWsfONNvmXaxHKMMWJPm1jVrL3TELc%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  ,  ir  (URL encoded) ,  qr  ,  limit  ,  offset  ,  sort  ,  sort_order  and  asgn  (URL Encoded)
https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&ir=%7B%22recommendation%22%3Atrue%7D&qr=true&limit=10&offset=20&sort=name&sort_order=asc&asgn=BCPevoXzusbBGiWsfONNvmXaxHKMMWJPm1jVrL3TELc%3D

Response

Upon making a successful request, if there are no errors, you will receive a JSON in one of the given formats
1) When a candidate has not taken the test
{
"status": "SUCCESS",
"candidates": [
{
"email": "name@email.com",
"registration": {
"Email Address": "name@email.com",
"First Name": "Name"
},
"testStatus": {
"status": "ToBeTaken",
                                "overallStatus":"Yet to start",
                               "detailedStatus":"Mapped"
},
"proctoringDetails": null
}
],
"paging": {
"previous": null,
"next": null
}
}

2) When a candidate's test in in progress
{
"status": "SUCCESS",
"candidates": [
{
"email": "name@email.com",
"registration": {
"Email Address": "name@email.com",
"First Name": "Name"
},
"testStatus": {
"status": "InProgress",
                                "overallStatus":"In-progress",
                               "detailedStatus":"In-progress",
"startTime": "Fri, 18 Feb 2022 02:37:24 GMT",
"lastResponseTime": ""
},
"proctoringDetails": null
}
],
"paging": {
"previous": null,
"next": null
}
}

3) When a candidate has finished the test but results are still being generated
{
"status": "SUCCESS",
"candidates": [
{
"email": "name@email.com",
"registration": {
"Email Address": "name@email.com",
"First Name": "Name"
},
"testStatus": {
"status": "InProcessing",
                                "overallStatus":"Completed",
                               "detailedStatus":"Test-taker Completed",
"startTime": "Fri, 18 Feb 2022 02:37:24 GMT",
"endTime": "Fri, 18 Feb 2022 02:39:58 GMT"
},
"proctoringDetails": null
}
],
"paging": {
"previous": null,
"next": null
}
}

4) When a candidate has finished the test and results are generated
4.1) When no optional parameters are sent
{
"status": "SUCCESS",
"candidates": [
{
"email": "name@email.com",
"registration": {
"Email Address": "name@email.com",
"First Name": "Name"
},
"testStatus": {
"status": "Completed",
                                "overallStatus":"Completed",
                               "detailedStatus":"Test-taker Completed",
"startTime": "Fri, 18 Feb 2022 01:09:52 GMT",
"endTime": "Fri, 18 Feb 2022 01:10:37 GMT",
"completionMode": "Completed",
"result": {
"totalMarks": 1.0,
"maxMarks": 2.0,
"percentile": 100.0,
"attemptTime": 45.078,
"candidateCredibilityIndex": "Not Applicable",
"totalQuestion": 2.0,
"totalCorrectAnswers": 1.0,
"totalUnAnswered": 0.0,
"sectionMarks": [
{
"sectionName": "Section Name",
"totalMarks": 1.0,
"maxMarks": 2.0,
"timeTaken": 0.0,
"totalQuestion": 2.0,
"totalCorrectAnswers": 1.0,
"totalUnAnswered": 0.0,
"skillMarks": [
{
"skillName": "Skill Name",
"totalMarks": 1.0,
"maxMarks": 2.0,
"timeTaken": 45.0,
"totalQuestion": 2.0,
"totalCorrectAnswers": 1.0,
"totalUnAnswered": 0.0,
"questions": null,
"difficultyMarks": [
{
"level": "EASY",
"totalQuestion": 2,
"totalMarks": 1.0,
"totalUnAnswered": 0,
"maxMarks": 2.0,
"timeTaken": 45,
"totalCorrectAnswers": 1,
"questions": null
}
]
}
],
"difficultyMarks": [
{
"level": "EASY",
"totalQuestion": 2,
"totalMarks": 1.0,
"totalUnAnswered": 0,
"maxMarks": 2.0,
"timeTaken": 45,
"totalCorrectAnswers": 1
}
],
"questionWiseResponse": null
}
],
"analysis": null,
"difficultyMarks": [
{
"level": "EASY",
"totalQuestion": 2,
"totalMarks": 1.0,
"totalUnAnswered": 0,
"maxMarks": 2.0,
"timeTaken": 45,
"totalCorrectAnswers": 1
}
],
                                    "codePlagiarism": "NA"
},
"performanceCategory": null,
"performanceCategoryVersion": null
},
"proctoringDetails": null
}
],
"paging": {
"previous": null,
"next": null
}
}

4.2) When  ir  parameter is enabled, the following highlighted parameters are sent in addition to the base response.
{
"candidates": [
{
"testStatus": {
"result": {
"analysis": {
"versionId": 999999,
"recommendation": [
{
"type": "Recommendation",
"value": "Cautiously Recommended"
}
]
}
}
}
}
]
}

4.3) When  qr  parameter is enabled, the following highlighted additional parameters are sent in the response.
{
"candidates": [
{
"testStatus": {
"result": {
"sectionMarks": [
{
"skillMarks": [
{
"questions": [
{
"type": "la",
"questionText": "<div>Question Text</div>",
"questionType": "Long Answer",
"marksScored": 0.0,
"maxMarks": 1.0,
"hasWordLimit": false,
"wordLimit": 0,
"wordCount": 5,
"candidateResponse": "<p>Essay response for manual grading</p>"
}
],
"difficultyMarks": [
{
"questions": [
{
"type": "la",
"questionText": "<div>Question Text</div>",
"questionType": "Long Answer",
"marksScored": 0.0,
"maxMarks": 1.0,
"hasWordLimit": false,
"wordLimit": 0,
"wordCount": 5,
"candidateResponse": "<p>Essay response for manual grading</p>"
}
]
}
]
}
]
}
]
}
}
}
]
}


OverallStatus and DetailedStatus

Overall Status
Detailed Status
Description
Yet to Start
Mapped
Test-takers have been added to a test-link via candidate banks or manual entry, but an email hasn’t been sent.
Yet to Start
Invited
Test-taker has been invited for the test via email.
Yet to Start
Registered
Test-taker has registered by clicking on proceed/submit button on the test-taker portal. 
Not Started
Access Expired
1-Test-taker didn't start the test and access time elapsed. 
2- Test-taker has registered by saving registration fields on test-taker portal but didn’t start the test and access time elapsed.
3- In case of deadline-based assessments, this status will be displayed when submission date is elapsed.
In-progress
In-progress
Test –taker has started the test 
In-progress
Awaiting Resume Permission
Test-taker got disconnected and is awaiting resume permission from admin (if Supervised resume is enabled). 
Completed
Test-taker completed
Test-taker clicked on the Finish button to submit the test. 
Completed
Time Over
The test was auto-submitted as the test-taker ran out of time. 
Test Stopped
Mic Mute Limit exceeded
The test was stopped because of exceeding mic mute count.
Test Stopped
Browsing Tolerance Limit Exceeded
The test was stopped because of exceeding Browsing Tolerance.
Test Stopped
Proctor Stopped 
Proctor stopped the test.
Test Stopped
Suspicious Software Detected
The test was stopped because of suspicious software. 
Test Stopped
Multiple Screen Detected
The test was stopped because of multiple screens detected.
Test Stopped
Prohibited Apps Running
The test was stopped because of prohibited apps running. 
Test Stopped
Screen Capture/Recording Detected
The test was stopped because of screen capture/recording. 
Test Stopped
Screen Sharing/Remote Access Detected 
The test was stopped because of screen share/remote access.
Blocked
Authorizer Blocked
The authorizer blocked the test-taker from starting the test.
Disconnected
Disconnected from Server
The test-taker got disconnected because of power failure/bad internet and couldn't resume within 30 minutes. 
Disconnected
Test Window Closed
Test-taker closed the window and navigated away from the screen. Test-taker didn't resume the test in 30 mins. 
Disconnected
Awaiting Test-taker Resume
The test-taker got disconnected and admin resumed the test (normal resume). 

Completion Modes

In the above response JSON, you will also receive a parameter called completionMode which can be helpful in understanding how a candidate's test got finished. The possible values for this parameter and their description can be found in table below- 

completionMode (in API Response)
Test Finish Mode (in Candidate Reports)

Description

AutoCompletedAuto SubmitTest Time finished before candidate could attempt all questions.
NABlocked Candidate blocked at the authorization stage (For Proctored Test with Authorization On).
BrowsingToleranceExceededBrowsing Tolerance ExceededWhen browsing tolerance is set and test taker navigates away from the test window more than the permissible number or times (browsing tolerance limit).
ExpiredExpiredIf candidate gets disconnect (Loss of internet connection, etc) or his/her system shuts down abruptly and he/she is unable to resume the test.
CompletedNormal Finish Test button Clicked.
ParentFinishedNormalThe background parent window is closed.
ProctoredFinish Proctored Finish Image Proctored Test ended by Proctor.
ResumeEnabledResume EnabledCandidate allowed to resume tests from same point where test got over, only can be done if initial status was Expired.
SuspiciousSoftwareFinish Suspicious Software FinishSuspicious Software detected Eg TeamViewer, SplashTop etc also found running and Mettl automatically closes test.
CandidateClosed Test Window ClosedTest Window Closed without clicking on Finish Test.