HireArt: The all-in-one-platform to source, employ, and manage contract W2 workers.

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 parameter, and values corresponding to the error messages associated with that parameter: <div class="CodeRay"> <div class="code"><pre>{ <span class="key"><span class="delimiter">"</span><span class="content">email</span><span class="delimiter">"</span></span>: [ <span class="string"><span class="delimiter">"</span><span class="content">This candidate already has a pending assessment for this interview.</span><span class="delimiter">"</span></span> ] }</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.

Get an API Key
Use [GET /interviews] endpoint to find an interview id
Use [POST /assessment] with the interview id to create an assessment
Use the application_url from POST /assessment to apply to the job
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

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

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>[
 {
 "id": 1,
 "completed": true,
 "created_at": "2014-11-25T18:10:58Z",
 "recommended": true,
 "url": "https://www.hireart.com/employers/candidates/bcfed383-54f4-49d0-99f7-6d53ffb87891",
 "detail": "The candidate has a strong command of marketing principles and techniques.",
 "application_url": "https://www.hireart.com/jobs/4e0ad82d/apply?ax=4lnqd8d7"
 },
 {
 "id": 2,
 "completed": true,
 "created_at": "2014-11-25T18:10:58Z",
 "recommended": false,
 "application_url": "https://www.hireart.com/jobs/4e0ad82d/apply?ax=4lnqd8d7"
 }
]</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>{
 "id": 1,
 "completed": true,
 "created_at": "2014-11-25T18:10:58Z",
 "recommended": true,
 "url": "https://www.hireart.com/employers/candidates/bcfed383-54f4-49d0-99f7-6d53ffb87891",
 "detail": "The candidate has a strong command of marketing principles and techniques.",
 "application_url": "https://www.hireart.com/jobs/4e0ad82d/apply?ax=4lnqd8d7"
}</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:

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.