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.
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.
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.
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.
https://{API Key}:{Password}@api.hiringthing.com
403 FORBIDDEN
The request was refused because the provided authorization credentials do not grant sufficient privileges.
https://{API Key}:{Password}@api.hiringthing.com/api/{API Endpoint}
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.
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.');
});
});
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)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.
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:
A String is a variable length UTF-8 encoded String
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
A Date is represented by a ISO 8601 compliant String with no time component: 2017-09-05. This represents Tuesday 5th September 2017
A Boolean has a value of true or false
An Integer is a 32-bit signed Integer
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.
200 OK
The request was successful
201 ACCEPTED
The request has been accepted for processing
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.
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.
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.
• 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
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.
Please email support at: support@hiringthing.com.
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.