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.
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: gzipAccept-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.
Authenticating API Calls with OAuth 2.0
Important Note: iCIMS recommends that all partners adopt OAuth 2.0 as their authentication method to authenticate API users. For information regarding Basic HTTP Authentication, review the Legacy API Authentication page.
iCIMS REST APIs are protected using the standards based OAuth 2.0 security protocol. In order for partners to access iCIMS APIs, they must establish an identity for the service calling the API, obtain permission to call the API by obtaining an access token, and use the access token as proof of authorization and identity to call APIs. Please review the Authenticating API Calls with OAuth 2.0 page for full details.
HMAC
The iCIMS Talent Platform also allows users to authenticate using HMAC. Please review Authenticating Requests Using HMAC for full details.
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)
Integration partners or clients who need to open their firewall for inbound SFTP/HTTP/HTTPS traffic from the iCIMS network can find the full list of IPv4 networks and ranges in the following iCIMS Knowledge Base article: iCIMS IP Addresses and Domains to Allow