Introduction

SmartRecruiters Analytics API data is grouped into data services.

Data service is a subset of all data we store in the system, crafted specifically to ease reporting and organized around a single concept from SmartRecruiters domain, such as “jobs”, “positions”, “applications” etc.

Data service can be also seen as a very big table. Each row in such a table represents an instance of some entity in the system (e.g. position or job) and each column describes some property of the entity (e.g. job title).

Each data service has exactly one dedicated endpoint in Analytics API that exposes its content to the API users.

Data Transfer

We use chunked transfer encoding for all successful requests to the Analytics API. It means that we will stream the data in chunks of variable size.

Data Compression

In order to improve transfer speed and bandwidth utilization, client may request compressed content. In order to to this, the addition HTTP request header Accept-Encoding: gzip has to be specified with the HTTP request.

Note: if the HTTP request header Accept-Encoding: gzip has been specified, the HTTP response content is gzip/binary (the Content-Encoding: gzip HTTP response header indicates compressed content) and has to be uncompressed on client side before further processing.

Data Format

We support two data formats in Analytics API responses: CSV (comma-separated values) and JSON (JavaScript Object Notation). Required data format can be selected by setting the Accept header on the HTTP request to either: text/csv or application/json.

Each line in CSV responses or each object in JSON responses is a data record. Each record consists of fields (separated by commas in CSV responses). Each field can be of one of the following types:

• String – used for fields that contain plain text.
• Enumeration – use for fields that can have limited number of defined values (e.g. status of a job).
• Number – used for numeric, integer fields.
• Boolean – used for fields with two possible values: true or false.
• Date – used for fields that denote date/time. If not stated otherwise, all dates are in UTC time zone and are expressed in ISO 8601. Date format can be customized for each request separately using the dateFormat parameter. For example, to ignore the time component of date fields, dateFormat parameter can be set to: dateFormat=yyyy-MM-dd.
• UUID – used for identifiers. See https://en.wikipedia.org/wiki/Universally_unique_identifier for more details.
• Float – used for numbers with a floating decimal point, specifically latitude and longitude.

Throttling Policy

You can make up to 1 request at a time (concurrent requests are rejected). We calculate a delay penalty for each additional request. Before you can call Analytics API again, you must wait proportionally to the amount of data you received. Delay penalty is calculated for each endpoint separately.

Once you exceed the limit calls we will return HTTP status 429 and a message telling you that you’ve been limited. Retry-After HTTP header will tell you how many seconds you must wait before you can make next request to the Analytics API.