19. Delete Result of Candidate in Schedule

19. Delete Result of Candidate in Schedule

Definition

This  DELETE  API is used to delete the status or result of a particular candidate in a schedule/ test link if the test has been “completed” or is “Expired”. The tests that are “in-progress” will remain unaffected. 
      *PDF documentation reference - Section 6.3 Fetch status of a test for a candidate

where, access-key is the unique key of the schedule/ test link from which you want to delete the status or result of a particular candidate,
and, candidate-email-id is the unique email Id of the candidate added to a schedule/ test link for which you want to delete the status or result.

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.

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.


 DELETE  request syntax with mandatory parameters:
https://api.mettl.com/v2/schedules/{access-key}/candidates/{candidate-email-id}?ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}      

Example

Request without Signature
a.  DELETE  request URL, with queries  ak  and  ts  but without  asgn  (Signature)
https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates/name@email.com?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 = "DELETE" +  "https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates/name@email.com"  + "\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)
2fOJwEt8zEe7SnrMRVjr0ko3CJvS9i1vkW9DGXkvjL8%3D
Read more about the above Signature Generation Process in API Authentication and Signature Generation

Request with Signature
f. Final  DELETE  request URL with queries  ak  ,  ts  and  asgn  (URL Encoded)
https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates/name@email.com?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&asgn=2fOJwEt8zEe7SnrMRVjr0ko3CJvS9i1vkW9DGXkvjL8%3D

Response

Upon making a successful request, if there are no errors, you will receive a JSON in the given formats
{
"status": "SUCCESS",
"candidateInstanceId": 99999999
}