Developer Resources

Error Reporting Standard for Vendors

In the event that a 3rd party vendor wishes to respond to an iCIMS request with error information, iCIMS has defined an Error Reporting Standard. This standard has three features.  

First, vendors must report errors by responding with the appropriate HTTP Status Code as defined below:

Error Type HTTP Status Code Definition
TEMPORARY ERROR 503 - Service Unavailable Used to express a temporary error, perhaps due to maintenance. 
USER ERROR 400 - Bad Request Used to express an error that can be resolved by the user. 
SYSTEM ERROR 500 - Internal Server Error

Used to express an error that requires intervention from Vendor and/or iCIMS HelpDesk.

Second, vendors specify a JSON error payload as follows:

{   
     "error":         {             
          "userMessage": "Please provide a valid US SSN before requesting Background Check.",
          "debugErrorMessage": "This request could not be processed because the required field US SSN was not populated."
     } 
}

The value specified in "userMessage" will be displayed to the end user. The value specified in "debugErrorMessage" will be logged and used for troubleshooting purposes.   

A final feature of Vendor Error Reporting worth mentioning is the ability to have 'encoded' field ids translated to platform-specific display values. In this context 'encoded' field id refers to the integrationFieldId used by Vendors to access particular pieces of data from the iCIMS platform. For example, consider the following call to retrieve a US SSN:

Sample Request: api.icims.com/customers/952/people/1230?fields=usssn

Furthermore, suppose that this field lacks a valid value (has no value or an invalid value) and because of this, the Vendor cannot process the original request. If the Vendor uses the JSON error payload format above and incorporates the invalid field using the following format: 

Encoded FieldID Format: {{profileType.IntegrationFieldId}}  

then the iCIMS Talent Platform will translate the integrationFieldId in question to the platform-specific display value. Continuing with the US SSN example, if the Vendor returns, "Request could not be processed because the value in {{people.usssn}} was invalid," iCIMS Talent Platform will display "Request could not be processed because the value in US SSN was invalid." Note that the bold (encoded) portion of the message will be displayed as the platform-specified value, thus taking into account any customizations that may have been performed by customer. (Note that invalid variables that cannot be resolved will be displayed as is.)

Additional examples include:

  • {{people.firstname}} to refer First Name field of Person Profile.
  • {{applicantworkflows.field1234}} to refer some custom field of Recruiting workflow Profile.

Supported Profile Types (and their prefixes for the format above) are as follows:

  • Person : people
  • Job: jobs
  • Recruiting Workflow: applicantworkflows
  • Onboarding Workflow: onboardworkflows
  • New Hire Categories: newhirecategories