Connecting, Authenticating and Identity

Guidelines

Please note that the HTTP specification dictates that all URLs, URIs, and parameters are case sensitive. In order to avoid confusion, iCIMS has made all URLs, URIs, parameters, headers, and JSON field names lowercase. The JSON document structure and metadata is lowercase, but the data contained within the JSON document is of mixed case. Users should always assume that they should be using entirely lowercase letters. 

Backwards Compatibility

iCIMS may add JSON fields (or HTTP headers) at any time, but we will not change or remove existing JSON fields.  This type of change should not cause issues to any existing integrations.  As such, iCIMS recommends that partners design each integration with these guidelines in mind to avoid any break in the event that iCIMS makes these benign changes. iCIMS recommends that developers treat the JSON payloads as a map of key value pairs and ignore new keys that appears in the map.  iCIMS discourages the use of strict schema validation of JSON messages in our API to allow the future enrichment of our API with new pieces of information.

API Endpoints

Customers and vendors working with customers hosted in iCIMS’ EU database must use api-eu.icims.com to ensure that API requests are routed to the customer using infrastructure hosted within the EU, allowing the customer to meet their EU regulatory obligations.

HTTP Transport Policy

iCIMS has guidelines regarding the transport settings used while interacting with iCIMS Web Service endpoints. All API Web Service traffic is required to use the HTTPS protocol. iCIMS will include a Strict Transport Security Header with each response with a maximum age of 90 days.

iCIMS only supports HTTP version 1.1, and all other HTTP versions will be rejected with a 505-HTTP Status Code.

By default and unless otherwise specified, an HTTP response and request should specify a valid Content-Length Header. All URL endpoints will reject request bodies greater than 2MB in size, except for exceptional endpoints such as those dealing with documents. If a client request is rejected, a 413-Request Entity Too Large Status Code is returned.

The default character encoding for JSON is UTF8 and the iCIMS API supports this specification.

Sample Request Headers

Host:api.icims.com 

Connection:  Keep-Alive 

Content-Encoding:gzip 
Accept-Encoding: gzip 

Accept-Language:en-US

Sample Response Headers

Strict-Transport-Security:max-age=7776000 

Connection:Keep-Alive 
Content-Encoding:  gzip 
Allow:GET,POST,PATCH,DELETE,HEAD. 
X-Content-Type-Options:nosniff

IP Address Restrictions

The Platform requires the use of IP address-based restrictions to restrict the range of network addresses allowed to use a set of credentials. In the event that an API request is made from an IP address not part of the configured IP Address range, a 403 Forbidden response code will be returned along with a specific error code such as 26:You may not access this services. Your IP address <Your IP Address> is not allowed.

Rate Limits

iCIMS enforces a rate limit on its Web Services API to ensure continuity of service for all customers. API clients are limited to 10,000 API calls per day per customer by default. As part of each Platform response, iCIMS includes the current rate limit set for the customer’s system, the number of available calls left for the day, and the number of seconds until the rate limits are reset. The rate limits are daily, and iCIMS treats the end of day as 12:00AM UTC. In the event an API client exceeds the rate limit for a given customer, a 429-Too Many Requests Status Code will be returned along with the X-RateLimit-* HTTP headers. API resources can enforce their own rate limit as a subset of the iCIMS global rate limit.

Sample Rate Limits Message:

X-RateLimit-Limit:10000 
X-RateLimit-Remaining:9893 
X-RateLimit-Reset:28800

Security

Beginning March 30, 2017, all integration traffic must use TLS 1.2 (or higher) encryption. Traffic utilizing SSL or TLS 1.0 (or lower) will not be allowed. 

User-Agent String

When connecting with iCIMS via API, vendors should identify their script or agent within the call through a User-Agent string. The "User-Agent" HTTP header is a standard HTTP header used to identify connecting client engines or browsers. While not required, providing this information assists with troubleshooting, when needed, for an easier and more streamlined experience. 

Vendors should use a specific User-Agent string that identifies who they are, what script or engine is interacting with iCIMS API and follow the below format. 

Format:

User-Agent : {What does this script do/who is making the call} / {version} (contact information such as website or email)

Example:

User-Agent :  Vendor-Name to iCIMS / 1.0.8 dev (http://vendor-website.com or email@vendor-webiste.com)

If a vendor has multiple endpoints or multiple sets of code, it is requested that each endpoint is identified individually.

For example, a vendor has two endpoints - one that initiates a background check (endpoint A) and one that submits a completed background check (endpoint B). In this scenario, each endpoint could be uniquely identified as follows:

Endpoint A

User-Agent : VendorName BG Initiator / 2.1.5 (http://vendor-site.com)

Endpoint B

User-Agent : VendorName BG Completions / 2.2 (http://vendor-site.com)