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
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
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-Typeheaderapplication/json; charset=utf-8 and an
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.
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
This represents Tuesday 5th September 2017
A Boolean has a value of true or false
An Integer is a 32-bit signed Integer
HTTP Responses 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.
The request was successful
The request has been accepted for processing
The request was refused as the provided authorization credentials do not grant
404 NOT FOUND
The resource, such as a Job, could not be found.
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
You've exceeded your rate limits. By default these are 50 requests per second and 500 requests within a 60
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.
Examples of "Minor Changes":
Adding new attributes to the JSON response
Adding new endpoints
Changing the type of ID attributes (most ID attributes will be integers, but you should not assume
Changing the order in which attributes are presented in the response
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.