Creating an Assessments Integration

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:

1. The API implemented by Ashby
2. The API implemented by the assessment partner.

The general flow of the assessments framework is as follows:

1. 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.
2. 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.
3. 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.
4. 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 a 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:

1. identifier: The identifier 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 on assessment_status, for example, then there shouldn't exist other data in the payload (e.g. in assessment_result, metadata, etc.) that also have that same identifier.
2. value: This is the raw value itself, for that data field.
3. type: This is the type of the value. These are semantic types, so types that start with numeric_ should be a number, types that start with boolean_ should be a boolean, string and url 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.
4. label: This is meant to be a human-readable string, which we will display in the UI in Ashby to label the value.
5. 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 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.

Custom Fields

An assessments partner can optionally implement an additional endpoint to supply a list of custom fields that can be synced to Ashby. If you wish to use this feature, please contact Ashby as it must be enabled for your integration.

The custom fields flow has 3 parts:

1. When enabling the integration, Ashby will call /customField.list, an API implemented by the partner, to provide the Ashby user with a list of custom fields that they can choose to sync.
2. The user will select which fields they wish to use in Ashby from the integration admin pane. This will create custom fields in Ashby that are linked to the integration.
3. When starting an assessment, data from those fields is sent in the payload to /assessment.start.

What the Assessments Partner Implements for Custom Field Sync

As an assessment partner, if you wish to use custom field sync for your integration, one additional endpoint must be implemented.

This endpoint will be called relative to the same base URL as the other endpoints specified above. Ashby will make requests to this API using the same authentication mechanism as other endpoints.

POST /customField.list

When an Ashby customer has enabled the integration and provided authentication information, Ashby will call this endpoint to get a list of available custom fields and their configuration.

A call to /customField.list should accept an empty request body and return a JSON-formatted list of custom field specifications.

In Ashby, the customer will choose which of these fields they wish to use.

What Ashby Implements for Custom Field Sync

When custom field sync is enabled for your integration, the values entered into any enabled fields will be sent in the request to /assessment.start as an additional parameter additional_fields. This parameter will be a mapping of ids as specified in the specifications received to values entered in Ashby.