5. Add PBTs

5. Add PBTs

Definition

This  POST  API is used to add Pre Built Tests from Mercer | Mettl's library to the list of Assessments in your account using PBT Ids which can obtained using Get All PBTs API

Request Header

contentType: 'application/x-www-form-urlencoded; charset=UTF-8'

Request Body


Key

Value
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.

pbts

The list of PBTs you want to add to your account. A PBT can added using the PBT Id  in the given JSON format , which can be obtained using Get All PBTs API.

[pbtId1, pbtId2, pbtId3, pbtId4, ..... ]

for eg
[1336,1255,1176]


 POST  request syntax:
Request URL:
ak={Public-Api-Key}&ts={Timestamp}&asgn={Signature}&pbts={PBT-list}

Example

Request without Signature
a.  POST  request URL, with request body  ak  ,  ts  and  pbts   but without  asgn  (Signature)
Request URL:
Request Body:
ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&pbts=[1336,1255,1176]

b. Creating a String-to-Sign, calculated with Method + Endpoint + Request Body, in new lines and in ascending order of the parameter name (i.e., the new line characters "\n" followed by values of  ak  ,  pbts  and  ts  in order, for this example)
String-to-Sign = "POST" +  "https://api.mettl.com/v2/pbts"  + "\n" + "ab12c345-6789-0123-456d-78e9f0123456"  + "\n" + "[1336,1255,1176]" + "\n" + "1635976200"
c. Output of the String-to-Sign created above
ab12c345-6789-0123-456d-78e9f0123456
[1336,1255,1176]
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)
Cbb5V47%2FzJB9VZ2NY3uQGbeIDXV1tblw2QGjZdHZGmA%3D
Read more about the above Signature Generation Process in API Authentication and Signature Generation

Request with Signature
f. Final  POST  request URL with request body  ak  ,  ts  ,  pbts   and  asgn  (URL Encoded)
Request URL:
Request Body:
ak=ab12c345-6789-0123-456d-78e9f0123456&ts=1635976200&pbts=[1336,1255,1176]&asgn=Cbb5V47%2FzJB9VZ2NY3uQGbeIDXV1tblw2QGjZdHZGmA%3D

Response

Upon making a successful request, if there are no errors, you will receive a JSON in the given format
{
"status": "SUCCESS",
"pbts": [
{
"pbtId": 1336,
"added": true,
"message": "Mettl Leadership Assessment(1336) has been added successfully with assessment Id : 756452",
"assessmentId": 756452,
"pbtName": "Mettl Leadership Assessment"
},
{
"pbtId": 1255,
"added": true,
"message": "Mettl High Potential Assessment(1255) has been added successfully with assessment Id : 756453",
"assessmentId": 756453,
"pbtName": "Mettl High Potential Assessment"
},
{
"pbtId": 1176,
"added": true,
"message": "Mettl Managerial Potential Assessment(1176) has been added successfully with assessment Id : 756454",
"assessmentId": 756454,
"pbtName": "Mettl Managerial Potential Assessment"
}
]
}

If one or more of the PBTs you are trying to add, are already in your account, then you will get an error response. In such a scenario, only those PBTs will be added to your accout which are not already added. This can be seen in the sample response below indicated by the "added" and "message" parameters. Since PBT with Id 1336 was already added, the same cannot be added again.
{
"status": "ERROR",
"pbts": [
{
"pbtId": 1336,
"added": false,
"message": "Exception: pbt assessment already added",
"assessmentId": 0,
"pbtName": null
},
{
"pbtId": 1151,
"added": true,
"message": "Mettl Test for Critical Thinking(1151) has been added successfully with assessment Id : 759172",
"assessmentId": 759172,
"pbtName": "Mettl Test for Critical Thinking"
}
]
}