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 a 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 assessment to mutual customers.

  1. 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.
  2. Integration Partner is open to use UX that fits best in their platform so that mutual customer can send an assessment to a particular candidate. Partner can use our Send Test API endpoint to let us know about candidate details and the requested assessment to be sent. Adaface sends an email invite to candidate automatically and returns a trackable unique Adaface id for the invite.
  3. Once 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.

API

Base API id

We create separate API endpoints for every partner so that it's seamless to customize the API if required. Get your "partnerId" from your Adaface account manager.

List Tests API

GET: https://www.adaface.com/app/api/integrations/<partnerId>/list_tests
HEADERS: Authorization: Basic <unique customer key>

Assume that "pinkfloyd" is the unique key that Adaface manager gave to our mutual customer who gives it to partner's team or inputs into partners dashboard.  Say, your unique partnerId that we gave you is "rambo". Then the request will be

curl 'https://www.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:

{
    "partner_test_id": <testId>
    "partner_test_name": <testName>
}

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": "cool-dragon-23",
        "partner_test_name:: "Software Engineer Test"
    },
    {
        "partner_test_id": "small-mouse-33",
        "partner_test_name": "Javascript Developer Test"
    }
]

Send Test API

POST: https://www.adaface.com/app/api/integrations/<partnerId>/send_test
HEADERS: authorization: Basic <unique customer key>
BODY: {
    partner_test_id: <testId that mutual client chose. available from list tests api>,
    candidate: {
        first_name: <first name of candidate>,
        last_name: <last name of candidate>,
        phone_number: <phone number of candidate>,
        email: <email id of candidate. Required>
    }
}

Let's say mutual client chose to send "Software Engineer Test" (check sample response from above List Tests API) 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 looks:

curl -X POST 'https://www.adaface.com/app/api/integrations/rambo/send_test'
-H "Authorization: Basic pinkfloyd"
{
    "partner_test_id": "cool-dragon-23",
    "candidate":
    {
        "first_name": "John",
        "last_name": "Doe",
        "email": "ada@adaface.com"
    }
}

Response to this API request is an object with one key "partner_interview_id". Partners are expected to save this internally to fetch the results later. (Optionally you can provide us a PUSH url so that we push the results to your endpoint instead. Speak with your assessment partner for such integration). Sample response:

{
    "partner_inteview_id": "12345678"
}

Test status API

GET: https://www.adaface.com/app/api/integrations/<partnerId>/test_status?partner_interview_id=<partnerInterviewId>
HEADERS: Authorization Basic <unique customer key>

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",
    "results_url": <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 the interview_id "12345678", assuming partnerId as "rambo" and customer key as "pinkfloyd". Here's the sample request and response:

curl 'https://www.adaface.com/app/api/integrations/rambo/test_status?partner_interview_id=12345678'
    -H "Authorization: Basic pinkfloyd"
{
    "status": "completed",
    "results_url": "https://www.adaface.com/app/scorecard/87654321"
}

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

Questions?

Please reach out to us at deepti@adaface.com for any questions or special requests.