We’ve created the Integration Partner API to allow our partners to seamlessly integrate Adaface assessments into their workflow. This document outlines the technical details of how to implement the integration.
Working with Adaface to implement the integration
An Adaface account manager will work with an integration partner throughout the integration process for seamless onboarding to the integration. If you do not have an account manager yet, please write to deepti@adaface.com, and we'll get in touch within 24 hours.
Workflow
Using our integration APIs, marketplace partners can create an engaging experience for skills assessments for mutual customers.
After receiving the API key for a mutual customer from the Adaface account manager, an integration partner can use List Tests API endpoint to retrieve the list of assessments available for sending to candidates for that particular customer.
The Integration Partner is free to use UX that best fits their platform so that mutual customers can trigger an assessment to a particular candidate. Partner can use our Send Test API endpoint to let us know about candidate details and the assessment to be sent. Adaface sends an email invite to candidate automatically and returns a trackable unique Adaface id for the invite.
Once a candidate completes the assessment, the results are available on Test Status API endpoint. Integration partner is expected to poll our API to know when the assessment is complete. Optionally, if the integration partner has a PUSH API, Adaface uploads the results on this given API immediately once the candidate completes the assessment. To setup a PUSH API flow, inform your Adaface account manager.
PartnerId
We create separate API endpoints for every partner so that it's seamless to customize the API if required. You can get your "partnerId" from your Adaface account manager.
List Tests API
GET: https://app.adaface.com/app/api/integrations/<partnerId>/list_tests HEADERS: Authorization: Basic <unique customer API key>
Assume that "pinkfloyd" is the unique API key that the Adaface account manager set up for a mutual customer who gives it to partner's team or inputs it into partner's dashboard. Say, your unique partnerId is "rambo". Then the request will be:
curl 'https://app.adaface.com/app/api/integrations/rambo/list_tests' -H "Authorization: Basic pinkfloyd"
Response to this API request is a JSON array with each individual array element having below schema:
{
"adafaceTestId": <unique_test_id>,
"testName": <test_name>,
"testDuration": <test_duration_in_mins>,
"cutOffPercentage": <cut_off_percentage>
}You can use this list in your UI/UX for the mutual customer to choose a particular assessment that's available to them. Sample response:
[
{
"partner_test_id": "pretty-mouse-39",
"partner_test_name": "Sample Assessment",
"test_duration": 3600,
"test_cut_off_percentage": 70
}
]
Send Test API
Call this API when you want to send a test to a candidate. Here's the API schema with all possible input options:
POST:
https://app.adaface.com/app/api/integrations/<partnerId>/send_test
HEADERS: authorization: Basic <unique customer API key>
BODY:
{
"adafaceTestId": <test id from list_tests response>,
"candidate": <object with candidate details>,
"turnOffInviteEmail": <if Adaface should not send invite email>,
"turnOffReminderEmails": <if Adaface should not send reminders>,
"callbackUrl": <callback url Adaface will use to POST the results>,
"replyTo": <email id string or comma separated email ids | optional>
}
Let's say a mutual customer chose to send "Software Engineer Test" to a candidate with email id as "ada@adaface.com" and name as "John Doe" where unique customer key is "pinkfloyd" and partnerId is "rambo". Here's how the request will look:
curl -X POST 'https://app.adaface.com/app/api/integrations/rambo/send_test' -H "Authorization: Basic pinkfloyd" { "adafaceTestId": "cool-dragon-23", "candidate": { "firstName": "John", "lastName": "Doe", "email": "ada@adaface.com" } }
Here are the details about the options in the request body:
adafaceTestId: Mandatory field. You will get the test id from List Tests API.
candidate: Mandatory field. An object with one mandatory key- "email". Optionally, you can include "firstName" and "lastName" in the object.
turnOffInviteEmail: Optional field. Adaface sends an invite email to the candidate. If you do not want Adaface to send an invite email, you can send 'true' for this key.
turnOffReminderEmails: Adaface sends reminder emails to the candidate at different intervals. Optional field. If you do not want Adaface to send reminder emails, you can send 'true' for this key.
callbackUrl: Optional field. When a candidate completes the assessment, Adaface uses this callbackUrl to POST the candidate results. (More on this in Test Status API),
replyTo: Optional field. Send one email id or a group of email ids comma separated as a single string. When the candidate replies to the invite emails or reminder emails, the reply comes to the email ids passed as replyTo.
Response to the Send Test API request is an object with two keys "adafaceInterviewId" and "candidateInviteLink". Partners are expected to save "adafaceInterviewId" (unique id for each assessment invite sent to a candidate) to be used to fetch the assessment results later. "candidateInviteLink" is the web URL at which the candidate will take the assessment. If you use "turnOffInviteEmail", we leave it to you to send the invite link to candidates. Sample response:
{
"adafaceInterviewId": "017EAC4DCAE3",
"candidateInviteLink": "https://app.adaface.com/app/017EAC4DCAE3/start"
}
Test status API
Use this API to get the test result of an assessment invite.
POST:
https://www.adaface.com/app/api/integrations/<partnerId>/test_status
HEADERS: Authorization Basic <unique customer API key>
BODY:
{
"adafaceInterviewId": <adaface interview id sent from Send Test API>
}
You can poll our test status API to know status of the sent test. Here's the response to such a request:
{
"status": <status> // one of "pending", "completed" or "expired",
"scorecardLink": <url> // unique link for full detailed scorecard. present only when status is "completed"
}
If your UX requires more details about the results like "score", "maxScore" etc, speak with your Adaface manager and we will send more metadata for your partnerId.
For the interview_id "12345678", assuming partnerId as "rambo" and customer key as "pinkfloyd". Here's the sample request and response:
POST:
https://app.adaface.com/app/api/integrations/rambo/test_status
HEADERS:
Authorization: Basic pinkfloyd
BODY:
{
"adafaceInterviewId": 12345678
}'
{
"status": "complete",
"scorecardLink": "https://app.adaface.com/app/scorecard/016EA5C5CEF0/helpless-wolverine-3"
}
Test Status Polling
The recommended way to fetch the results of an assessment is to use test_status API. You can stop the poll after any of the following events happen:
"status" is "completed" or "expired"
10 days have passed since the invite is sent
We recommend polling it in a 4-hour interval.
Test Status Push
We support webhook method of receiving results of an assessment. For this, when you call Send Test API, you are expected to include "callbackUrl". When candidate completes the assessment or if invite is cancelled/expired, we make a POST call to the callbackUrl with same response as produced by our Test Status API.
Even if you use Test Status Push method, we recommend implementing Test Status Polling since we do not guarantee that the webhook method will work 100% of the time. If the webhook API fails due to network latency or server issues, we do not retry the POST call to the webhook API.
List Interview Ids API
Use this API to get interview ids of all the invites of your account (including the ones sent via API and via Adaface dashboard)
POST:
https://www.adaface.com/app/api/integrations/<partnerId>/list_interview_ids
HEADERS: Authorization Basic <unique customer API key>
BODY:
{
"before": <optional | unix timestamp in milliseconds>
}
The results of this API will be of the format:
{
"interviewIds": [ list of interviewIds ],
"next": [ time stamp for pagination],
"error" "If there is any error in producing the response"
}Note that the interviewIds will be sorted by invite sent time in descending order. By default the page limit is 500 interview Ids (this is not changeable). If there are more than 500 results, you will receive "next" parameter in the response. "next" value will be a timestamp in milliseconds and is to be passed as "before" in the same API to retrieve next set of 500 results.
List Interview Ids of a Candidate API
Fetch interview ids or status details of a particular candidate:
POST:
https://www.adaface.com/app/api/integrations/<partnerId>/list_candidate_interviews
HEADERS: Authorization Basic <unique customer API key>
BODY:
{
"email": <email id of the candidate>,
"includeStatus: true or false (default: false)
}
The response would be of the following format if includeStatus is set to false OR if includeStatus is true but there are more than 10 matching interviewIds for the particular candidate.
{
"error": <If there is any error in producing the response>,
"interviewIds": [list of interviewIds of the candidate],
}We do not recommend using includeStatus as true unless required. The suggested usage is to fetch interviewIds of the candidate and then calling test status API for each of those interviewIds.
If includeStatus is set to true and there are lesser than 10 interviewIds for the particular candidate, then the response would be of this format:
[
<status of each interviewId of this candidate. check test status API for details on this object>
]
Caching
When possible, we recommend caching the interviewId and test status details in your own database so that there is no need for re-fetching every time your UX requires the details.
Testing
For testing, Adaface account manager will provide integration partner with a test Adaface account as well as test customer API key (along with partner id).
Error
All of the APIs, if any error happens will respond with following response:
{
"error": "Reason for the error"
}
We recommend that you check for 'error' key in the response of all APIs. If the key is not present, then you can assume the request was a success. We are standardising our error responses. If you get a generic error, do reach out to us for help with debugging.
Rate Limits
We do not have set rate limits at the moment but we expect you to use the APIs sensibly. When we set the rate limits, we will communicate them to you.
Questions?
Please reach out to us at deepti@adaface.com for any questions or special requests.