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 – 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.
• Interview API – Enables customers and partners to integrate their self-scheduling or interview management tool to create and manage interviews in SmartRecruiters.
• Message API – Enables customers to create and delete Notes on candidate applications and send email notifications to users @-mentioned in the note.
• 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 APIs

Customer API endpoints can be accessed in 3 ways, depending on the desired result:

• Without Authentication – Available only to specific endpoints which contain publicly available data: Posting API, Common Elements.
• API Key – This authentication method is dedicated to customers building their own integrations, apps or connectors meant to be used only by them (not productised) or integrations that won’t have any user facing interface.
• OAuth 2.0 – Is dedicated for productised apps, integration or connectors that are meant to be used by multiple SmartRecruiters users and made available in SmartRecruiters Marketplace

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. Do note that objects and fields name in requests and responses are case sensitive.

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:

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.