API Docs

Overview

Our API allows you to interact with our system programmatically from your own application. Using the API, you can access resources such as Jobs, Applicants, Notes and others. All of your account and applicant data is fully available through our secure account API. You can see all of your applicants, edit jobs, send emails, edit account information, edit applicant information, get real time data about your hiring campaigns. Everything that is available in the web application is available through our API.

Who is the API for?

We created the API to allow software engineers an easy way to work with our application. You can create customized solutions that work best for your specific use case by integrating our RESTful API’s into your software projects. We make this a seamless process by giving developers the client libraries they need to make API calls in many popular software languages including: c#, Python, Ruby, PHP, Java, JavaScript, etc.

If client libraries don’t cover everything needed for the project you’re working on, you can connect with the API directly by making the HTTP calls in the language of your choice. You can explore our API interactively here (menu option API Endpoints), or you can use tools like Postman or cURL. If you’d like to explore the API interactively here, you must be logged in to your account.

Note that when you use cURL, you may need to add the -L option. This allows cURL to automatically follow 301 Moved Permanently re-directs. We use existing standards to simplify integration. Our API supports the use of JSON – each request should specify the Content-Type header application/json; charset=utf-8 and an Accept header application/json.

Authentication

Overview

The authentication scheme implemented is HTTP Basic Authentication over HTTPS using an API Key and Password. You must access our API over HTTPS not HTTP. HTTP is not supported by the API. HTTPS is required to ensure that your credentials are not exposed in transit.

How to get an API Key and Password

In order to access the API you must have an API Key and Password. If you are new to HiringThing and want to use our API in your project you will first need to create an account. Sign up for a HiringThing account.

Authentication Request

https://{API Key}:{Password}@api.hiringthing.com

Error Responses

403 FORBIDDEN

The request was refused because the provided authorization credentials do not grant sufficient privileges.

Make a request

Request URL
https://{API Key}:{Password}@api.hiringthing.com/api/{API Endpoint}

 

URL Placeholders
  • { API Key } – API Key from “Account Details->API” page.
  • { Password } – API Password from “Account Details->API” page.
  • { API Endpoint } – This is a placeholder for the endpoint you want to make a request to.
Make a request

You can make a request using the programming language of your choice or use one of our SDK’s for convenience. Here are some request examples using a few popular web development languages.

Request Example – Node.js
const https = require('https');
const api_key = '04b23c4a-934b-11e7-abc4-cec278b6b50a',
api_pass = 'ff926a28-599b-4869-b620-a0b2ca905cfb',
options = {
hostname: '${api_key}:${api_pass}@api.hiringthing.com/api/jobs'
method: 'GET',
};
https.request(options, (res) => {
res.setEncoding('utf8');
res.on('data', (chunk) => {
console.log(`BODY: ${chunk}`);
});
res.on('end', () => {
console.log('No more data in response.');
});
});

 

Request Example – Ruby
require 'net/http'

api_key = "04b23c4a-934b-11e7-abc4-cec278b6b50a"
api_pass = "ff926a28-599b-4869-b620-a0b2ca905cfb"
uri = "https://#{api_key}:#{api_pass}@api.hiringthing.com/api/jobs"

Net::HTTP.get(uri)

API Response

Our API follows the JSON API specification giving developers a well structured and documented format to work with. Part of the benefit of using the JSON API spec is built-in data that makes the developers life easier.

Some of these features are built in pagination links that help to limit boilerplate code, and structured data that is identical across API resources. Please checkout the JSON API docs for in-depth documentation of the API’s JSON structure.

Response Data Types

Each API returns one or more data objects – for example, one of the Jobs you have created. The basic data types within these objects include:

STRING

A String is a variable length UTF-8 encoded String

TIME

A Time is represented by a ISO 8601 compliant String that is in the timezone of the HiringThing site: 2017-09-05T14:30:00EDT

This represents Tuesday 9th September 2017 at 2:30PM Eastern Daylight Time

DATE

A Date is represented by a ISO 8601 compliant String with no time component: 2017-09-05. This represents Tuesday 5th September 2017

BOOLEAN

A Boolean has a value of true or false

INTEGER

An Integer is a 32-bit signed Integer

HTTP Response Codes

We use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a job could not be found,etc.), and codes in the 5xx range indicate an error with our servers.

Success Responses

200 OK

The request was successful

201 ACCEPTED

The request has been accepted for processing

Error Responses

403 FORBIDDEN

The request was refused as the provided authorization credentials do not grant sufficient privileges.

404 NOT FOUND

The resource, such as a Job, could not be found.

422 UNPROCESSABLE

The request was unable to be processed due to it containing invalid parameters. The response will contain a JSON object containing one or more errors relating to the invalid parameters. For example, if when creating a Job you omitted the required job_description field, you would receive a response like:


{
"errors": {
"job_description": [
{
"key": "errors.required",
"description": "required"
}
]
}
}

429 TOO MANY REQUESTS

You’ve exceeded your rate limits. By default these are 50 requests per second and 500 requests within a 60 second window. Your code should stop making API requests temporarily when encountering such a response.

500 SERVER ERROR

The request was unable to be processed due to an error with our servers.

API Versioning

Overview

We use API versioning to indicate major changes to our APIs. If there are significant changes to the behavior of an API, or to its request parameters or responses, we will create a new version of the API.

Backwards Compatibility

All previous versions of the API will remain supported. Response structure and data will also remain unchanged for the most part. The caveat being, minor changes that are deemed too small to warrant a full new API release. All other major changes will be versioned. We will always announce these minor changes to the current API version before they are implemented. This is to ensure that you have ample time to make the required tweaks to your application.

Examples of “Minor Changes”:

• Adding new attributes to the JSON response

• Adding new endpoints

• Changing the type of ID attributes (mostly integers, but you should not assume this)

• Changing the order in which attributes are presented in the response

API Customization

What we offer

We are happy to customize our API to meet your special use case and business needs. If there is any functionality you would like to see that is currently absent from our API we would be happy to discuss adding that for you. Please contact customer support so we can discuss what your needs are and help create a customized solution that works for you.

Request API Customization

Please email support at: support@hiringthing.com.

Support

We’re always happy to help – if you run into any issues with our APIs, please send an email to: support@hiringthing.com. If you’re reporting what seems to be an issue with an API, please try it out here first and send us as much information as you can to help us understand the issue. Screenshots can be a big help – sharing a Postman collection is also a useful aid getpostman.com/docs/postman/collections/sharing_collections

Often, the simplest approach can help when trying to debug calls to our API – cURL with the--verbose flag can give valuable insights.