10. Get All Schedules in Assessment

10. Get All Schedules in Assessment

Definition

This  GET  API is used to fetch the details of all schedules/ test links in an assessment (such as schedule name, id, access key, access URL along with the proctoring and security settings).
      *PDF documentation reference - Section 4.4 Get all schedule details for an Assessment

where, assessment-id is the unique Id of the assessment from which you want to fetch the details of all schedules/ test links.

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

filter

This is a JSON string containing details of Schedules/ Test Links to be used as a filter from the list of all Schedules/ Test Links in an Assessment. The format for the JSON is given below.


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

JSON ( filter )

Format of JSON string to be passed in query parameter  filter  can be found in the table below. This JSON describes the details of the Schedules/ Test Links to be filtered.  

PropertySub PropertySub PropertyDescription
visualProctoring

Filters for Advanced Visual Proctoring settings. This value is a nested JSON .
↳mode
Filters results where Advanced Visual Proctoring is enabled when "PHOTO" is chosen. This value is a string and only accepts "PHOTO" or "OFF".
↳options
Filters for additional settings of Advanced Visual Proctoring when enabled. This value is a nested JSON .                    

↳candidateScreenCaptureFilters results where screen-grabs of candidates test screen is enabled when true is chosen. This value is a boolean.

↳candidateAuthorizationFilters results where manual live authorization process is enabled for starting the test when true is chosen. This value is a boolean.
webProctoring

Filters for Browsing tolerance settings. This value is a nested JSON.
↳enabled
Filters results where Browsing tolerance is enabled when true is chosen. This value is a boolean and mandatory within webProctoring propertry.
↳count
Filter for the number of times a test taker is allowed to navigate away from the test window, before the test ends. This value is an integer and should be more than or equal to 0. 
↳showRemainingCounts
Filters results where showing remaining counts of Browsing tolerance is enabled when true is chosen. This value is a boolean.
type

Filters results for Open access or Private invitation only schedules/ test links. This value is a string and only accepts "OpenForAll" or "ByInvitation".
scheduleType

Filters results for access time settings in schedules/ test links. This value is a string and only accepts "AlwaysOn" or "Fixed".
limit

Number of schedules/ test links to fetch from your assessment. This value is an integer and only accepts a value from 1 to 100, with the default value being 20.

available in v3 only.
offset

Returns the list of the schedules/ test links offset from the starting position. This value is an integer and only accepts a value from 0 to 1 less than the total number schedules in your assessment, with the default value being 0.

available in v3 only.

Sample  filter  JSON with all properties:
{
"visualProctoring": {
"mode": "PHOTO",
"options": {
"candidateScreenCapture": true,
"candidateAuthorization": true
}
},
"webProctoring": {
"enabled": true,
"count": 10,
"showRemainingCounts": true
},
"type": "ByInvitation",
"scheduleType": "Fixed",
"limit": 5,
"offset": 10
}

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/999999/schedules?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/assessments/999999/schedules"  + "\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)
X68OBU49AKMpQw%2BiJQQ83JCBnUv3sNdgM2Jz9qiQXMw%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/999999/schedules?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&asgn=X68OBU49AKMpQw%2BiJQQ83JCBnUv3sNdgM2Jz9qiQXMw%3D

2) Request with all query parameters
Request without Signature
a. GET request URL, with queries  ak  ,  ts  and  filter  but without  asgn  (Signature)
https://api.mettl.com/v2/assessments/999999/schedules?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&filter=%7B%22webProctoring%22%3A%7B%22enabled%22%3Atrue%7D%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  ,  filter  and  ts  in order, for this example)
String-to-Sign = "GET" +  "https://api.mettl.com/v2/assessments/999999/schedules"  + "\n" + "ab12c345-6789-0123-456d-78e9f0123456"  + "\n" + "{"webProctoring":{"enabled":true}}" + "\n" + "1635976200"
c. Output of the Sting-to-Sign created above
ab12c345-6789-0123-456d-78e9f0123456
{"webProctoring":{"enabled":true}}
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)
%2FhVQ8evMz3Zxpem3irZV0RQnTMAJ%2BHTMw5wKjjKXRzo%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  ,  filter  and  asgn  (URL Encoded)
https://api.mettl.com/v2/assessments/999999/schedules?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&filter=%7B%22webProctoring%22%3A%7B%22enabled%22%3Atrue%7D%7D&asgn=%2FhVQ8evMz3Zxpem3irZV0RQnTMAJ%2BHTMw5wKjjKXRzo%3D

Response

Upon making a successful request, if there are no errors, you will receive a JSON in the given format
{
"status": "SUCCESS",
"schedules": [
{
"id": 7342702,
"name": "Test Link 1",
"accessKey": "0x0x0x0x0x",
"status": "ACTIVE",
"createdAt": "Wed, 02 Feb 2022 03:19:50 GMT",
"imageProctoring": false,
"webProctoring": {
"enabled": false
},
"scheduleType": "AlwaysOn",
"scheduleWindow": {
"fixedAccessOption": null,
"startsOnDate": null,
"endsOnDate": null,
"startsOnTime": null,
"endsOnTime": null,
"timeZone": null,
"locationTimeZone": null
},
"access": {
"type": "OpenForAll",
"candidates": null,
"sendEmail": null,
"sendReminders": null,
"isCandidateCrfPrefilled": false
},
"ipAccessRestriction": {
"enabled": false
},
"sourceApp": "Mettl",
"testStartNotificationUrl": null,
"testFinishNotificationUrl": null,
"testGradedNotificationUrl": null,
"testResumeEnabledForExpiredTestURL": null,
"isCandidateAuthProctored": false,
"testGradeNotification": {
"enabled": false,
"recipients": null
},
"visualProctoring": {
"options": {
"candidateScreenCapture": false,
"candidateAuthorization": false,
"audioOptional": true,
"isAudioProctoring": false
},
"mode": "OFF"
},
"allowTestResume": "UnSuperVised",
"secureBrowser": {
"enabled": false
},
"protected": "NotEnabled"
},
{
"id": 7342680,
"name": "Test Link 2",
"accessKey": "x0x0x0x0x0",
"status": "ACTIVE",
"createdAt": "Wed, 02 Feb 2022 03:14:52 GMT",
"imageProctoring": true,
"webProctoring": {
"enabled": true,
"count": 10,
"showRemainingCounts": true
},
"scheduleType": "AlwaysOn",
"scheduleWindow": {
"fixedAccessOption": "ExactTime",
"startsOnDate": "Wed, 02 Feb 2022",
"endsOnDate": "Thu, 03 Feb 2022",
"startsOnTime": "00:00:00",
"endsOnTime": "00:00:00",
"timeZone": "UTC+00:00",
"locationTimeZone": null
},
"access": {
"type": "ByInvitation",
"candidates": [
{
"name": "Name",
"submissionDate": null,
"email": "name@email.com"
}
],
"sendEmail": false,
"sendReminders": false,
"isCandidateCrfPrefilled": false
},
"ipAccessRestriction": {
"enabled": false
},
"sourceApp": "Mettl",
"testStartNotificationUrl": null,
"testFinishNotificationUrl": null,
"testGradedNotificationUrl": null,
"testResumeEnabledForExpiredTestURL": null,
"isCandidateAuthProctored": true,
"testGradeNotification": {
"enabled": false,
"recipients": null
},
"visualProctoring": {
"options": {
"candidateScreenCapture": true,
"candidateAuthorization": true,
"audioOptional": true,
"isAudioProctoring": false
},
"mode": "PHOTO"
},
"allowTestResume": "UnSuperVised",
"secureBrowser": {
"enabled": true
},
"protected": "NotEnabled"
}
]
}