15. Register Candidates in Schedule

15. Register Candidates in Schedule

Definition

This  POST  API is used to generate a candidate specific unique test links for each candidate in a schedule/ test link.
      *PDF documentation reference - Section 6.1.2 Option 2 – Register candidate(s) for a test & receive notifications on Test start, completion, grading, resume enabled

Endpoints

  1. https://api.mettl.com/v2/schedules/{access-key}/candidates 
  2. https://api.mettl.com/v1/schedules/{access-key}/candidates
where, access-key is the unique key of the schedule/ test link for which you want to generate candidate specific test links.

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.

Remarks

Using this API you can create candidate specific test links for a candidate using an access key and candidate registrations fields. You can generate a link for any candidate in a  public or "OpenForAll" schedule, but in a private or "ByInvitation" schedule, test links can only be generated when a candidate has already been added to the schedule.

This API is also used in the third step of our sample API Integration Flow with "OpenForAll" schedules for generating unique test links for each candidate to send emails from your own custom Id in your integration. Alternatively for sending emails from a Mercer | Mettl Id, you can edit a private schedule with candidate info and 'sendEmails' equal to true, instead of using this 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.

rd

This is a JSON string containing the details of the candidates for generating candidate specific test links. You can send the details of up to 20 candidates at once. The format for the JSON is given below


 POST  request syntax with mandatory parameters:
https://api.mettl.com/v2/schedules/{access-key}/candidates?ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}&rd={Regisration-Details-JSON} 
Optional parameters


Query Parameter


Description

allowMissingMandatoryRegistrationFields

Allows you to skip the mandatory fields while registering a candidate. The candidate has to fill the remaining mandatory fields to start the test. The mandatory Fields “Email Address”, “First Name” cannot be skipped using this parameter.

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

timeLimitInSec

Allows generating links that expire after the specified time limit in seconds.

You can input a value greater than 0, with the default functionality resulting in test links that don't expire.

showCustomInstructions

Allows you to show custom instructions that been set in the assessment, to be displayed to the candidate before the assessment starts.

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


 POST  request syntax with mandatory parameters:
https://api.mettl.com/v2/schedules/{access-key}/candidates?ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}&rd={Regisration-Details-JSON}&allowMissingMandatoryRegistrationFields={Boolean}&timeLimitInSec={Link-Expiry-Limit-in-Sec}&showCustomInstructions={Boolean}

JSON ( rd )

Format of JSON string to be passed in query parameter  rd  can be found in the table below. This JSON describes the details of candidate(s) to be registered.
If the assessment is created in any other language than English, then users need to first get Candidate Registration Fields in that language and then register candidates accordingly.
Note: In the  rd  JSON below,  properties  highlighted with the color yellow are always mandatory.

PropertySub PropertyDescription
registrationDetails
Registration Details of the candidate for which you want to generate an encrypted test link. This list of nested JSON(s) is mandatory and accepts details of up to 20 candidates at a time.

eg. [{"First Name": "Name", "Email Address": "name@email.com", "Date of birth": "Sep 16 1998"},{"First Name": "Name2", "Email Address": "name2@email.com", "Date of birth": "Jan 1 1996"}]
Email AddressCandidate's email Id. This string is mandatory and has to be unique for each candidate in a schedule/ test link.
First NameCandidate's name. This string is mandatory
*exact name of other Candidate Registration FieldsThis property represents all other candidate registration fields and the name of the property is the exact name of the registration field. This string is mandatory depending on the mandatory registration fields configured in an assessment or account but can be skipped using  allowMissingMandatoryRegistrationFields .
optionalParams
Metadata of the candidate for which you want to generate an encrypted test link. This list of nested JSON(s) is optional and accepts details of up to 20 candidates at a time.
emailCandidate's email Id to which you want to add context metadata. This string is optional and only accepts email Ids which is part of the registrationDetails above.
context_dataMetadata of candidates who are being registered. This metadata would then be passed back in Webhook notifications and on demand results. This string is optional

For easier readability, the sample  rd  JSON below has pretty formatting, but in your actual request and for signature generation, they should be ideally minified.
Sample  rd  JSON with all properties:
{
"registrationDetails": [
{
"First Name": "Name",
"Email Address": "name@email.com"
}
],
"optionalParams": [
{
"email": "name@email.com",
"context_data": "metadata"
}
]
}

Examples

1) Request with only mandatory query parameters
Request without Signature
a.  POST  request URL, with queries  ak  ,  ts  and  rd  (URL encoded) but without  asgn  (Signature)
https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&rd=%7B%22registrationDetails%22%3A%5B%7B%22First%20Name%22%3A%22Name%22%2C%22Email%20Address%22%3A%22name%40email.com%22%7D%5D%7D

b. Creating a String-to-Sign, calculated with Method + Endpoint + Values of query parametersin new lines and in ascending order of the parameter name (i.e., the new line characters "\n" followed by values of  ak  ,  rd  and  ts  in order, for this example)
String-to-Sign = "POST" + "https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates" + "\n" + "ab12c345-6789-0123-456d-78e9f0123456" + "\n" + "{"registrationDetails":[{"First Name":"Name","Email Address":"name@email.com"}]}" + "\n" + "1635976200"
c. Output of the String-to-Sign created above
ab12c345-6789-0123-456d-78e9f0123456
{"registrationDetails":[{"First Name":"Name","Email Address":"name@email.com"}]}
1635976200
d. Private-API-Key to sign/hash the above String-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 String-to-Sign and your Private-API-Key, hashed with HMAC-SHA256 (Base-64 and URL Encoded)
t72%2BcLqiOZPD4qIKLuabKh2czEebF6ELG8kZt%2F4HPRQ%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  ,  rd  (URL encoded) and  asgn  (URL Encoded)
https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&rd=%7B%22registrationDetails%22%3A%5B%7B%22First%20Name%22%3A%22Name%22%2C%22Email%20Address%22%3A%22name%40email.com%22%7D%5D%7D&asgn=t72%2BcLqiOZPD4qIKLuabKh2czEebF6ELG8kZt%2F4HPRQ%3D

2) Request with all query parameters
Request without Signature
a.  POST  request URL, with queries  ak  ,  ts  ,  rd  (URL encoded) ,  allowMissingMandatoryRegistrationFields  ,  timeLimitInSec  and  showCustomInstructions  but without  asgn  (Signature)
https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&rd=%7B%22registrationDetails%22%3A%5B%7B%22First%20Name%22%3A%22Name%22%2C%22Email%20Address%22%3A%22name%40email.com%22%7D%5D%7D&allowMissingMandatoryRegistrationFields=true&timeLimitInSec=86400&showCustomInstructions=true

b. Creating a String-to-Sign, calculated with Method + Endpoint + Values of query parametersin new lines and in ascending order of the parameter name (i.e., the new line characters "\n" followed by values of  ak  ,  allowMissingMandatoryRegistrationFields  ,  rd  ,  showCustomInstructions  ,  timeLimitInSec  and  ts  in order, for this example)
String-to-Sign = "POST" + "https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates" + "\n" + "ab12c345-6789-0123-456d-78e9f0123456" + "\n" + "true" + "\n" + "{"registrationDetails":[{"First Name":"Name","Email Address":"name@email.com"}]}" + "\n" + "true" + "\n" + "86400" + "\n" + "1635976200"
c. Output of the String-to-Sign created above
ab12c345-6789-0123-456d-78e9f0123456
true
{"registrationDetails":[{"First Name":"Name","Email Address":"name@email.com"}]}
true
86400
1635976200
d. Private-API-Key to sign/hash the above String-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)
lWKjNsV4fiEbn0TtKKp38vFwwnzATfEqKHBZ%2FlCmNHc%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  ,  rd  (URL encoded) ,  allowMissingMandatoryRegistrationFields  ,  timeLimitInSec  ,  showCustomInstructions  and  asgn  (URL Encoded)
https://api.mettl.com/v2/schedules/0x0x0x0x0x/candidates?ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&rd=%7B%22registrationDetails%22%3A%5B%7B%22First%20Name%22%3A%22Name%22%2C%22Email%20Address%22%3A%22name%40email.com%22%7D%5D%7D&allowMissingMandatoryRegistrationFields=true&timeLimitInSec=86400&showCustomInstructions=true&asgn=qsLTfT3m7XG6ASBIECit2R%2Bzr2z6xk8QlV8R1jouO8Q%3D

Response

Upon making a successful request, if there are no errors, you will receive a JSON in the given format
{
"status": "SUCCESS",
"registrationStatus": [
{
"email": "name@email.com",
"status": "ToBeTaken",
"message": "Candidate ('name@email.com') successfully registered for the test",
}
]
}