Overview

*Note: We’ve made several updates to our Customer API endpoints as of January 2018 that may impact your existing integrations. Please see our Changelog for all updates.


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 – Enables 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.
  • 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.
  • 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.
  • 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.
  • Reporting API – Is a collection of endpoints that opens API access to custom reports created in Report Builder.

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

Connect to the Customer API

Obtaining an API key

Customers can easily connect to the Customers API using an API key. You must have a SmartRecruiters user account with Admin system role to access your own dedicated API key. You can obtain the API key in the API / Integrations section in your SmartRecruiters account.

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. If you want to allow a 3rd party or partner to access your data, we recommend to use the OAuth method described here: https://dev.smartrecruiters.com/customer-api/authentication/.

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 Policies

The Customer API is guarded by several throttling policies. Each time a request violates a throttling policy, it will receive a response with http status 429 TOO MANY REQUESTS. The request rejection reason is placed in the HTTP headers of a response corresponding to the violated policy.

Below you can find descriptions of all throttling policies.

Note: All throttling policies are applied to an individual Customer API user.

Number of requests per time period

Current limit

The Customer API limit is 10 requests per second.

Exceptions

For the following endpoints, the limit is 2 requests per second:

  • POST /jobs/{id}/publication
  • DELETE /jobs/{id}/publication

Response headers

The following headers are present in a response regardless of whether a policy was violated:

  • X-RateLimit-Limit – the request limit for the time period
  • X-RateLimit-Remaining – the number of requests remaining until the time period passes

Number of concurrent requests

Current limit

The Customer API limit is 8 concurrent requests.

Exceptions

For Analytics API endpoints, only 1 concurrent request is allowed.

Response headers

The following headers are present in a response regardless of whether a policy was violated:

  • X-RateLimit-Concurrent-Limit – the concurrent request limit
  • X-RateLimit-Concurrent-Remaining – the number of possible additional concurrent requests

Response size per time period

Current limit

The response size limit policy is applied only to the Analytics API. For those endpoints, the response size limit is 100,000 bytes per second. The limit is enforced independently on each Analytics API endpoint.

Response headers

The following headers are present on a response only when the throttling policy is violated, i.e. for responses with 429 status code:

  • Retry-After – the number of seconds after which your app will be permitted to make another request to the same resource.

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:

  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.
  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. Use our Reporting API for getting data for analysis. Reporting API is designed to serve big amounts of data as quickly and effectively as possible. Reporting 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 Reporting 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

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

The Reporting API serves responses in CSV format by default due to the tabular nature of the data.  

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

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:

{
    "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:

{
    "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:

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

Geocoding

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

{
    "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:

{
    "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.