• iCIMS Corporate Site
  • iCIMS Partners
  • Additional Resources
  • Recent Updates
  • FAQ
  • Login
  • GETTING STARTED
    • Getting Started
    • Integration Approval Process
    • How-To Videos
    • Acceptable Use Policy
    • Terms of Use
    • Release Notes
  • API
    • Licenses
    • Connecting, Authenticating, and Identity
    • Authenticating API Calls with OAuth 2.0
    • HMAC
    • Error Handling
    • Error Reporting Standard for Vendors
    • Field Types
  • Standard Integrations
    • Assessments
    • Candidate Matching
    • Candidate Ranking
    • Document Management
    • Data Analytics and Reporting
    • Human Capital Management
    • I-9 & E-Verify
    • Job Advertising
    • Job Posting
    • Partner Screening
    • Reference Checks
    • Tax Credits
    • Video Interviewing
  • Prime Integrations
    • Prime Assessments
    • Prime Background Screen
      • Implementation
  • Endpoints
    • Binary Collection Fields
    • Binary Files
    • Collection Fields
    • Customers
    • Direct Linking
    • iForms
    • Job Distributor
    • Job Portal API
    • List API
    • Offer API
    • Onboard API
    • Profiles
    • Schema API
    • Search API
    • Workflows
  • Streaming Endpoints
  • Data Models
    • iForms
    • Job
    • Location
    • New Hire Category
    • Onboarding Workflow
    • Person
    • Recruiting Workflow
    • Room
    • Sourcing Workflow
    • Talent Pool
    • Event
    • Validation
  • Integration Events
    • Best Practices
    • Application Complete
    • Job Edit
    • Job Posting
    • Job Unposting
    • Onboard Portal Task
    • Status Flow Update
  • OTHER TECH
    • File-Based Transfers
      • Scheduled Import/Export Licenses
      • Imports
      • Exports
      • File Formatting
      • Import File Examples
    • SAML
    • Standard XML Feed for Job Boards
  • Forum

Search form

Developer Resources
  • Getting Started
  • API
    • Licenses
    • Connecting, Authenticating, and Identity
    • Authenticating API Calls with OAuth 2.0
    • HMAC
    • Error Handling
    • Error Reporting Standard for Vendors
    • Field Types
  • Standard Integrations
  • Prime Integrations
  • Endpoints
  • Streaming Endpoints
  • Data Models
  • Integration Events
  • OTHER TECHNOLOGY
  • FAQ

Connecting, Authenticating and Identity

Connecting
Authenticating
Identity
IP Addresses to Allow for Integration Traffic
Connecting

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

iCIMS maintains two endpoints for its customers’ integration traffic: api.icims.com and api-eu.icims.com. 
 

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. 

Authenticating

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.

Identity

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)

IP Addresses to Allow for Integration Traffic

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

 

 

Do you have any questions or feedback regarding iCIMS' API documentation? Email the team
See Recent Site Updates

© 2023 iCIMS, Inc. All rights reserved.
Privacy Notice | Terms of Use