Creating an Assessments Integration
A guide on how to integrate with Ashby's Assessments Framework
Ashby's Assessments framework allows third party assessment providers to integrate with Ashby and allow users to initiate skills tests, reference checks, and background check processes from within Ashby.
The Assessments Partner API has 2 parts:
- The API implemented by Ashby
- The API implemented by the assessment partner.
The general flow of the assessments framework is as follows:
- An Ashby user will decide which assessment to send out as part of their interview plan. Ashby will call
assessment.list
, an API implemented by the partner, to provide the Ashby user with a list of assessments that they can choose from. - When a candidate reaches the appropriate part of the interview plan, the Ashby user will be notified to start the assessment. Ashby will call
assessment.start
, an API implemented by the partner, to trigger the partner to start an assessment. - As the assessment progresses and its status evolves, the partner will call
assessment.update
, an API implemented by Ashby, to provide status updates back to Ashby. - At any time an Ashby user may cancel the assessment, in which case
assessment.cancel
, an API implemented by the partner will be called to cancel the assessment.
More details can be found below:
What Ashby Implements
POST /assessment.update
Ashby implements /assessment.update
, which is called after an assessment has been started by call to /assessment.start
on the partner. /assessment.update
is called to update Ashby about progress, or any other new detail, about a started assessment.
About the /assessment.update Payload
Most data passed to /assessment.update follows a specific format (a JSON blob that has an identifier
, value
, type
, label
, and description
) that allows partners flexibility and control over display of that data in Ashby's UI. This format is non obvious, so let's walk through how it works:
identifier
: Theidentifier
serves as a key that uniquely identifies that data field, with respect to other data provided to/assessment.update
, for a given partner. These don't need to be globally unique identifiers, but if you provided an identifier called "status" for the data set onassessment_status
, for example, then there shouldn't exist other data in the payload (e.g. inassessment_result
,metadata
, etc.) that also have that same identifier.value
: This is the raw value itself, for that data field.type
: This is the type of the value. These are semantic types, so types that start withnumeric_
should be a number, types that start withboolean_
should be a boolean,string
andurl
should be strings, etc. If as a partner you feel like your data could be better represented by a type that is not yet listed, please reach out! We would love to support it.label
: This is meant to be a human-readable string, which we will display in the UI in Ashby to label thevalue
.description
: This is an optional description, which we can display in the UI to give users extra context about what the value means.
What the Assessments Partner Implements
As an assessments partner, you implement 3 APIs, which allow Ashby's customers to start and interact with your supported assessments, which map to the lifecycle of an assessment.
These APIs will be called relative to a base URL, which you will provide to Ashby, as part of becoming an Ashby assessments partner. Ashby will make requests to these APIs using Basic Auth, via an API key that customers will enter into the Ashby admin panel.
POST /assessment.list
When an Ashby customer has chosen you as the partner, from whom they would like to choose an assessment, to use in a candidate's interview plan, Ashby will call the this endpoint to list those assessments that are available for use in Ashby.
A call to /assessment.list
should accept an empty request body and return a JSON-formatted list of assessment types, which include the id, name, and optional description, of each assessment type.
In Ashby, the customer will choose one of the assessment types returned from this list, and it will be saved to that job's interview plan.
POST /assessment.start
Once a candidate reaches the stage of the interview plan where the candidate is to take the assessment, the customer will start the assessment, which will call /assessment.start
on the partner.
A call to /assessment.start
should accept information about the kind of assessment to start, as well as job, candidate, and application information, and then it should start the assessment return the id of the started assessment.
From this point forward, the partner should periodically call Ashby's /assessment.update
API to update Ashby on the progress, or any additional details, about the ongoing assessment.
POST /assessment.cancel
After the assessment has started, the customer may opt to cancel the assessment, for any number of reasons (e.g. bad data passed to the partner, in which case the data will be corrected and /assessment.start
retried). A call to /assessment.cancel
should accept the id of the assessment to cancel, cancel the assessment, and then return the id of the cancelled assessment.
Updated 9 months ago