Overview

About Customer API

The Customer API provides our customers and partners with a platform to integrate their services or applications they’re using, building their own apps and creating fully customizable career sites. It exposes SmartRecruiters functionality and allows to connect and build software enhancing it.

The Customer API is a REST API created for application developers to enable seamless integration with our SmartRecruiters platform. It is divided into several components:

  • Posting API – Allows customers to build fully customizable career sites and partners to build widgets.  This API contains snapshots of all published jobs as of last time published.
  • Job API – Enables customers to extract and import jobs’ data to / from SmartRecruiters platform as well as for partners to build applications that can be consumed by customers.
  • Application API – Enables customers and partners to integrate into their own site the full candidate application including screening questions, allows new applications to be submitted, and exposes the status of previously submitted applications.
  • Candidate API – Enables customers to import, export, read, and update candidate data.
  • User API – Enables customers to extract and import users’ data to / from SmartRecruiters platform as well as for partners to build applications that can be consumed by customers.
  • Configuration API – Enables customers to extract and import configuration data to / from SmartRecruiters platform as well as for partners to build applications that can be consumed by customers.
  • Analytics API – Is a collection of endpoints specifically built to allow users to download data extracts for reporting and analytics purposes.

The following sections describe how to connect and interact with the API.

Key and Authentication

Posting API does not require authentication as it exposes data that are already publicly available.

All other SmartRecruiters API will require an API key. The API key is a unique 32-characters string that is auto-generated for each SmartRecruiters user account.

Obtain the API key

You can obtain the API key in the API / Integrations section in your SmartRecruiters account.
Every SmartRecruiters user has their own dedicated API key. If you want to use our APIs to integrate with other systems, we recommend to have a dedicated Admin user and API key for each integration.

Pass the API key

You can pass the API key for authentication using X-SmartToken – http request header.

Example:

curl -i -H "X-SmartToken: abc123" -X GET https://api.smartrecruiters.com/jobs

Throttling and limits

To properly support all our users and ensure stability and continuity of our services we use adaptive throttling meaning that the limits of calls per second actively change according to the platform’s load at a given time. From your perspective it means that response times may vary significantly depending on the current state of the platform. Of course we will serve your requests as quickly as possible taking into account that the platform is shared and other users need to get the service too. You have a great influence on how your service behaves in the shared environment. If you follow the tips listed below you will get responses from the system faster and allow other users to use the platform unaffected:

  1. Program your software in the way that it does not make all the calls at one specific point of time, e.g.: 8 am, 9 am, etc. Build in instead some randomness and therefore distribute the calls in time more evenly. Our tooling detects traffic spikes and will not allow to serve too many requests simultaneously so that you can get significantly longer response times or receive errors if you try to execute too many requests at a specific time.
  2. Ensure that timeout of your requests is set to at least 128s. You shall receive response from our API servers within this time (a valid response or an error code). Of course we will do our best to answer your request as quickly as possible.
  3. Make no more simultaneous calls than the current limit allows. Parallel calls above the limit will return an http error code 429.
  4. Use our Analytics API for getting data for analysis. Analytics API is designed to serve big amounts of data as quickly and effectively as possible. Analytics API uses streaming to serve huge amounts of data as a response to one call so that there is no need to make multiple calls to iterate through the whole set. Throttling strategy on Analytics API ensures that you get full set of data at once and therefore you do not have to wait for the next chunk(s). There is a limit only when you can make the next call to the same endpoint.

Supported Formats

All requests and responses in the API use JSON by default.

Rest endpoints

An endpoint name to manage a particular resource is created using the plural form of a noun describing that resource. Customer API exposes customer-specific data, therefore a customerIdentifier has to be passed as part of the URL. The table below showcases a few examples:

Resource endpoint URL
Posting /postings GET https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings
Candidate /candidates GET https://api.smartrecruiters.com/candidates
Job /jobs GET https://api.smartrecruiters.com/jobs

Backward compatibility and a sunset of old API endpoints

We make all efforts to never break a schema of existing, publicly available API endpoints. Any changes we’re introducing are not breaking the schema. If there are such changes, those are introduced as a new version of an endpoint.
Both versions are maintained and available to developers.

If it ever happens that we’re going to change our policy and sunset any of our Public API endpoints, this is going to be announced to all impacted parties 4 months before the change is made with an appropriate steps to transition.

List resources

Getting a list of resources involves invoking the http GET request on a specific endpoint without passing the resource id:

GET https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings

The number of results returned by such a call differs between endpoints. You can control the number of retrieved items by specifying values for offset and limit:

GET https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings/?offset=10&limit=10

All other filtering parameters need to be specified as URL parameters:

GET https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings/?country=us

All lists returned by the API will be wrapped into a ListResult object. The ListResult object will have a limit, offset and totalFound number.

Paging

Resources paging can be implemented by using the offset, limit and totalFound properties of ListResult object. Let’s consider the following call:

GET https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings/?offset=0&limit=10

Below is a sample response body:

1
2
3
4
5
6
7
8
{
    "offset": 0,
    "limit": 10,
    "totalFound": 130,
    "content": [
        ...
    ]
}

This means that there are 130 resources found, out of which the response contains the first 10 (since offset is 0 and limit is 10). To get the next 10 resources, the following statement can be used:

GET https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings/?offset=10&limit=10

The response body for the above statement would be:

1
2
3
4
5
6
7
8
{
    "offset": 10,
    "limit": 10,
    "totalFound": 130,
    "content": [
        ...
    ]
}

Retrieve a single resource details

Getting a single resource requires sending an http GET request to a proper endpoint. A resource ID has to be passed as a part of the URL.

GET https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings/813192986

Response body will contain the queried resource or an error object if the invocation fails.

Error Handling

Customer API supports the following HTTP error codes:

  • 200 – OK
  • 400 – Bad Request
  • 500 – Internal Server Error

Apart from these three base http codes, Customer API response might also return:

  • 404 – Not Found
  • 401 – Unauthorized
  • 403 – Forbidden
  • 429 – Too many requests

Error responses will also contain a detailed error message.

Date and Time

All Date and DateTime fields will be formatted according to ISO 8601 standard. All dates with associated time zones will be given in UTC time zone. Date and Time values will be separated with the letter “T”. Time zone offset will be specified as +0000 (UTC time zone).

Example:

1
2
3
{
  "expirationDate": "2013-02-26T12:50:02.594+0000"
}

Geocoding

So far, all our APIs used the Location object to describe geocoding information.

1
2
3
4
5
{
    "country" : "us",
    "region" : "CA",
    "city" : "San Francisco"
}

With the new Job API we decided to update the Location object so it provides more precise and relevant information.

Example of the new Location object in Job API:

1
2
3
4
5
6
7
8
{
    "country": "United States",
    "countryCode": "us",
    "regionCode": "CA",
    "city": "San Francisco",
    "longitude": 41.40338,
    "latitude": 2.17403,
}

Required fields: countryCode, city (regionCode required for US Only)
countryCode has to be provided in lower case. regionCode has to be provided in upper case.
Longitude and latitude has to be provided in decimal degrees format (DDD).

We’re going to gradually update other APIs to incorporate this new standard.