API Overview

Purpose

This API exposes HireArt's assessment functionality, allowing partners to programmatically enqueue candidate assessments on our job seeker evaluation engine and retrieve the results once they're available.

Authentication

All calls to the HireArt assessment API require an API token, passed as the api_key parameter. This secret token uniquely identifies a partner and employer combination.

To obtain an API token, please send an email to api@hireart.com.

Format

All responses by the API will be formatted as JSON.

Response Status Codes

All successful requests return a 200 status code (GET requests) or a 201 status code (POST requests), along with the response objects described below. Errors will correspond to the following status codes:

Code Description
400 The request is malformed (e.g. API key is missing).
401 The API key is invalid.
403 The API key has successfully authenticated you, but you don't have authorization for this resource.
404 The resource requested cannot be found.
422 The request was well-formed, but there is a semantic error. Responses with this status code will include a JSON body with keys corresponding to each invalid parameters, and values corresponding to the error messages associated with that parameter: <div class="CodeRay"> <div class="code"><pre>{&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">email</span><span class="delimiter">&quot;</span></span>: [&#x000A; <span class="string"><span class="delimiter">&quot;</span><span class="content">This candidate already has a pending assessment for this interview.</span><span class="delimiter">&quot;</span></span>&#x000A; ]&#x000A;}</pre></div> </div>
500 There was an internal server error processing the request.
How to set up integration

Use api-sandbox.hireart.com endpoint to run tests. Contact api@hireart.com to get set up.

  1. Get an API Key
  2. Use [GET /interviews] endpoint to find an interview id
  3. Use [POST /assessment] with the interview id to create an assessment
  4. Use the application_url from POST /assessment to apply to the job
  5. Use [GET /assessment/:id] to check the status of the assessment

API Definition

All URLs referenced in this document have the following base:

https://api.hireart.com/v1

For our sandbox endpoint:

https://api-sandbox.hireart.com/v1

The HireArt API is served over HTTPS. To ensure data privacy, unencrypted HTTP requests are not supported.

Get All Interviews

GET /interviews

Gets a list of interviews that can be given to candidates.

Parameters
api_key
string
Required The API key
Sample Response
<div class="CodeRay"> <div class="code"><pre>[&#x000A; {&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">id</span><span class="delimiter">&quot;</span></span>: <span class="integer">1</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">name</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Marketing: Entry-level</span><span class="delimiter">&quot;</span></span>&#x000A; },&#x000A; {&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">id</span><span class="delimiter">&quot;</span></span>: <span class="integer">2</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">name</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Customer Service: Entry-level</span><span class="delimiter">&quot;</span></span>&#x000A; }&#x000A;]</pre></div> </div>

The response consists of an array of hashes with the following keys:

id
integer
The ID of the interview
name
string
The name of the interview

Create Assessment

POST /assessments

Creates a new assessment for a candidate given an interview.

Parameters
api_key
string
Required The API key
interview_id
integer
Required The ID of the interview that we want the candidate to complete
candidate[email]
string
Required The email address of the candidate
candidate[first_name]
string
The candidate's first name
candidate[last_name]
string
The candidate's last name
candidate[phone_number]
string
The candidate's phone number, either in E.164 format or unformatted (sequence of digits).
candidate[resume_url]
string
A URL pointing to the candidate's resume file
suppress_candidate_email
boolean
Default is false and will email the candidate with the assessment url. When true, the candidate will not be emailed automatically.
candidate[external_id]
string
The unique ID for this candidate in your application system
Sample Response
<div class="CodeRay"> <div class="code"><pre>{&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">id</span><span class="delimiter">&quot;</span></span>: <span class="integer">1</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">completed</span><span class="delimiter">&quot;</span></span>: <span class="value">false</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">created_at</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2014-11-25T18:10:58Z</span><span class="delimiter">&quot;</span></span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">application_url</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">https://www.hireart.com/jobs/4e0ad82d/apply?ax=4lnqd8d7</span><span class="delimiter">&quot;</span></span>&#x000A;}</pre></div> </div>

The response consists of a hash with properties of the assessment object:

id
integer
The ID of the assessment
completed
boolean
Whether the assessment is complete. Always false on creation.
created_at
string
The time at which the assessment was created, as an ISO 8601 formatted time string, in UTC.
application_url
string
The url link for the application.

Get All Assessments

GET /assessments

Gets all assessments associated with your account

Parameters
api_key
string
Required The API key
Sample Response

If there are no assessments an empty array will be returned. Otherwise, an array of matching assessments will be returned:

<div class="CodeRay"> <div class="code"><pre>[&#x000A; {&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">id</span><span class="delimiter">&quot;</span></span>: <span class="integer">1</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">completed</span><span class="delimiter">&quot;</span></span>: <span class="value">true</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">created_at</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2014-11-25T18:10:58Z</span><span class="delimiter">&quot;</span></span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">recommended</span><span class="delimiter">&quot;</span></span>: <span class="value">true</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">url</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">https://www.hireart.com/employers/candidates/bcfed383-54f4-49d0-99f7-6d53ffb87891</span><span class="delimiter">&quot;</span></span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">detail</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">The candidate has a strong command of marketing principles and techniques.</span><span class="delimiter">&quot;</span></span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">application_url</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">https://www.hireart.com/jobs/4e0ad82d/apply?ax=4lnqd8d7</span><span class="delimiter">&quot;</span></span>&#x000A; },&#x000A; {&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">id</span><span class="delimiter">&quot;</span></span>: <span class="integer">2</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">completed</span><span class="delimiter">&quot;</span></span>: <span class="value">true</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">created_at</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2014-11-25T18:10:58Z</span><span class="delimiter">&quot;</span></span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">recommended</span><span class="delimiter">&quot;</span></span>: <span class="value">false</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">application_url</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">https://www.hireart.com/jobs/4e0ad82d/apply?ax=4lnqd8d7</span><span class="delimiter">&quot;</span></span>&#x000A; }&#x000A;]</pre></div> </div>

The response consists of an array of hashes with properties of the assessment object

id
integer
The ID of the assessment
completed
boolean
Whether the assessment is complete
created_at
string
The time at which the assessment was created, as an ISO 8601 formatted time string, in UTC
recommended
boolean
Present if completed is true. Whether HireArt recommends this candidate based on the interview.
url
string
Present if recommended is true. A URL pointing to the full assessment on HireArt's website.
detail
string
Present if recommended is true, and may be present if false. A short blurb explaining why HireArt recommends this candidate.
application_url
string
The url link for the application.

Get Assessment

GET /assessments/:id

Gets the latest data for an assessment.

Parameters
api_key
string
Required The API key
id
integer
Required Passed as part of the URL. The ID of the assessment we want to query.
Sample Response

If the assessment has not yet been completed, the response of this endpoint will be the same as that given by the creation endpoint. Once the assessment is complete there will be additional fields. If the candidate is recommended by HireArt, the response will look like this:

<div class="CodeRay"> <div class="code"><pre>{&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">id</span><span class="delimiter">&quot;</span></span>: <span class="integer">1</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">completed</span><span class="delimiter">&quot;</span></span>: <span class="value">true</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">created_at</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2014-11-25T18:10:58Z</span><span class="delimiter">&quot;</span></span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">recommended</span><span class="delimiter">&quot;</span></span>: <span class="value">true</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">url</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">https://www.hireart.com/employers/candidates/bcfed383-54f4-49d0-99f7-6d53ffb87891</span><span class="delimiter">&quot;</span></span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">detail</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">The candidate has a strong command of marketing principles and techniques.</span><span class="delimiter">&quot;</span></span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">application_url</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">https://www.hireart.com/jobs/4e0ad82d/apply?ax=4lnqd8d7</span><span class="delimiter">&quot;</span></span>&#x000A;}</pre></div> </div>

If the candidate is not recommended by HireArt, the url field will be absent, and the detail field may be absent as well:

<div class="CodeRay"> <div class="code"><pre>{&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">id</span><span class="delimiter">&quot;</span></span>: <span class="integer">1</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">completed</span><span class="delimiter">&quot;</span></span>: <span class="value">true</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">created_at</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2014-11-25T18:10:58Z</span><span class="delimiter">&quot;</span></span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">recommended</span><span class="delimiter">&quot;</span></span>: <span class="value">false</span>,&#x000A; <span class="key"><span class="delimiter">&quot;</span><span class="content">application_url</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">https://www.hireart.com/jobs/4e0ad82d/apply?ax=4lnqd8d7</span><span class="delimiter">&quot;</span></span>&#x000A;}</pre></div> </div>

The response consists of a hash with properties of the assessment object:

id
integer
The ID of the assessment
completed
boolean
Whether the assessment is complete
created_at
string
The time at which the assessment was created, as an ISO 8601 formatted time string, in UTC
recommended
boolean
Present if completed is true. Whether HireArt recommends this candidate based on the interview.
url
string
A URL pointing to the full assessment on HireArt's website.
candidate_email
string
The email of the candidate.
interview_id
string
The id of the Interview.
detail
string
Present if recommended is true, and may be present if false. A short blurb explaining why HireArt recommends this candidate.
application_url
string
The url link for the candidate to begin the application.