• 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

Field Types

The sections below describe the different field types available and their representation when retrieving their values as well as the expected representations when modifying them.

For any field types, a null or empty string can be provided as the value to delete its value from the Profile.

Text
URL
Email
Number
Decimal
Textarea
HtmlEditor
Datetime
Dateonly
Dropdown
Dropdown (Multi-Select Save Reference)
Single Select (List Editor)
Multiple Select (List Editor)
Profile Link
Company Address Link
Salary
Currency
Image
File
Collections
Text
Term Description
GET Returns the text value

{
  “firstname”:“John”
}

SET A text value is expected
URL
Term Description
GET Returns the URL value. Any text values can be stored to this field, so a "real" URL is not guaranteed.

{
  “url”:“http://www.icims.com”
}

SET A URL value is expected. Any text values can be stored to this field, so a "real" URL is not enforced.
Email
Term Description
GET Returns the email value. Any text values can be stored to this field, so the "real" email is not guaranteed.

{
  “email”:“john.smith@iCIMS.com”
}

SET An email value is expected. Any text values can be stored to this field, so the "real" email is not guaranteed.
Number
Term Description
GET Returns a whole number value

{
  “numberofpositions”:4
}

SET A whole number value is expected
Decimal
Term Description
GET Returns a decimal value

{
  “experienceyears”:2.5
}

SET A decimal value is expected
Textarea
Term Description
GET Returns a string of text

{
  “synopsis”:“This is some text.”
}

SET A string of text is expected
HtmlEditor
Term Description
GET Returns a string of text that may contain HTML markup

{
  “field1234”:  “This is <b>bold<b> text!”
}

SET A string of text that may contain HTML markup is expected
Datetime
Term Description
GET Returns the date and time value in UTC in the format yyyy-mm-dd hh:mm a

{
  “field5678”:“2010-01-31 12:31 PM”
}

SET The date and time value in UTC in the format yyyy-mm-dd hh:mm a is expected
Dateonly
Term Description
GET Returns the date value in the format yyyy-mm-dd

{
  “field3456”:“2010-01-31”
}

SET The date value in the format yyyy-mm-dd is expected
Dropdown
Term Description
GET Returns the value of the selected drop-down option

{
  “gender”:"male”
}

SET [text] is expected

{
  “gender”:“female”
}

Dropdown (Multi-Select Save Reference)
Term Description
GET

{

    "<Field Integration Id>": [

        { 

            "id": <List Node Id>, 
            "formattedvalue": <Node display value, formatted>, 
            "value": <Node Display Value>
            },
            ... and continuing for any selected values.
        ]
    }

SET

{

   “<Field Integration Id>”:[
    {
      “id”:<Field's List Node Child Id 1>,
    },
    {

      “id”:<Field's List Node Child Id 2>,

    },
    ...
    {

      “id”:<Field's List Node Child Id N>,

    },
  ]
}

 

Single Select (List Editor)
Term Description
GET Returns the JSON object containing the ID and display value of the selected list node

{
  "folder":{
    “id”:“D1234”,
    “value”:“Cand:Active”
  }
}

SET The Default ID or Custom ID of a list node that is part of the n-level list that is associated with this field is expected.

Or by value (not recommended).

By Default ID (reference same n-level list node across customers, a value that comes with the system and is not individually made for a specific customer), use the D prefix and then the SystemID of the node:

{
  "folder":{
    “id”:“D1234”
}

By Custom ID (reference a specific n-level list node on a specific customer's system, that is unique to this customer), use the C prefix and the NodeId of the node:

{
  "folder":{
    “id”:“C2735”
}

By value, use the display value:

{
  "folder":{
    “value”:“active”
}

If both the id and value are provided, the id will always take priority over the value.

Note: For additional information about patching values for the School, Major, and Degree lists, please see the Person Profile Data Model page.

Multiple Select (List Editor)
Term Description
GET Returns a JSON array of JSON objects that contain the ID and display value of the selected list nodes

{
    "preferredindustries":[
    {
      “id”:C5432,
      “value”:“Health Care” 
    },
    {
      “id”:C9876,
      “value”:“Technology”
    }, 
    {
      “id”:C8923,
      “value”:“Financial”
    },
    {
      “id”:C7432,
      “value”:“Transportation”
    }
  ]
}

SET A JSON array of list node IDs that are part of the n-level list that is associated with this field is expected.

This is the same format as the Single Select List Editor field where a specific Default ID, Custom ID, or Value can be set to reference the n-level list node.

{
  "preferredindustries":[ 
    {
      “id”:C3879,
    },
    {
      “id”:C3886,
    }
  ]
}

 

Profile Link
Term Description
GET All the Profile Link fields (person, job, company, except the Company Address Profile Link field) will be in the following format.

This action returns a JSON object containing the display value (as it would on the Profile) and the performanceId.

The display value will be formatted in the following way for each type of field:

  • Person: firstName lastName
  • Job: jobTitle
  • Company: companyName
  • Address: companyName - street street2 city, state zip country
  • Custom Profile: title

{
"hiringmanager":{
     "profile":"https://api.dev.icims.com/customers/1234/people/1234567",
    "id":1234567,
    "value":"John Smith"
  }
}
 

SET The ProfileID (PersonID, JobID, CompanyID, PerformanceID) OR External ID can be used.

{
   "hiringmanager":1234567
}

OR

{
  "hiringmanager":{
    "id":1234567
  }
}

OR

{
  "hiringmanager":{
    "externalid":87654
  }
}
 

 

Company Address Link
Term Description
GET Returns a JSON object just like the Profile Link fields return with the difference being a companyId is also given and an API URL to access the address is given in. The id provided by this field is an addressId that points to a specific address on the specified company Profile.

{
  "location":{
    “id”:3,
“address”:“https://api.icims.com/customers/1234/companies/7/fields/addresses/3”,
    “value”:“iCIMS - 90 Matawan Road, Parkway 120, 5th Floor, Matawan NJ 07747, USA”, 
    “companyid”:7
  }
}

SET

Multiple options exist to set an addresslink field, including a specific address ID or a reference (ID or external ID) to a specific company profile

Specific Address ID:

With this option, the addresslink field is set with a specific address from a company profile

{
  "location":3
}

Company Profile ID or External ID:

With this option, the addresslink field is set with the default address from the referenced company profile 

{
    "location": {
        "company":{ 
            "id": 7
        }
    }
}
 

OR

 

{
    "location": {
        "company":{ 
            "externalid": "Northeast Region"
        }
    }
}
 

 

Salary
Term Description
GET Returns a JSON object containing the currency symbol, amount value, amount string, and time frame of the salary field

{
  "salary":{
    “currency”:“usd”, 
    “amount”:25, 
    “amountstring”:"25", 
    “timeframe”:“hourly”
  }
}

SET The same JSON object containing the currency symbol, amount value, amount string, and time frame is expected

{
  "salary":{
    “currency”:“usd”, 
    “amount”:35000, 
    “amountstring”:"35000", 
    “timeframe”:“yearly”
  }
}

 

Currency
Term Description
GET Returns a JSON object containing the currency symbol and amount value of the currency field

{
  "signingbonus":{
    “currency”:“usd”, 
    “amount”:5000
  }
}

SET The same JSON object containing the currency symbol and amount value is expected

{
  "signingbonus":{
    “currency”:“usd”, 
    “amount”:4000
  }
}

Image
Term Description
GET Returns an API URL to the image

{
"profilepicture":{
  “filename:”“profilePicture.jpg”,
  “file”:"https://api.icims.com/customers/1234/people/5/fields/profilePicture/binary"

  }
}

SET The value of this field cannot be set as with other Profile fields. Users must POST the URL directly to the field. Use the same URL as shown in the example above.
File
Term Description
GET Returns an API URL to the file

{
  "resume":{
    “filename”:“11574_catatatata_Hamilton_10859_Resume.doc”,
    “file”:"https://api.icims.com/customers/asd-231-1234-asd23/people/5/fields/resume/binary"
  }
}

SET The value of this field cannot be set as with other Profile fields. Users must POST the URL directly to the field. Use the same URL as shown in the example above.
Collections
Term Description
GET Returns a JSON array of up to a 100 (maximum capped, even if the system has more) collection groups JSON objects ordered in the same ordering as in the iCIMS Talent Platform, which is customizable per collection.

{
   “phones”:[
    {
      “entry”:23,
      “phonenumber”:“212-555-1234”,
      “phonetype”:“home”
    },
    {
      “entry”:24,
      “phonenumber”:“212-555-5678”,
      “phonetype”:“work”
    },
    {
      “entry”:25,
      “phonenumber”:“212-555-3456”,
      “phonetype”:“mobile”
    }
  ]
}

SET

The same format as when retrieving

Collections that support having a group marked as default can be set by specifying Default: true as an attribute value in the JSON.

To delete a collection group, specifying Delete: true as an attribute value in the JSON will trigger it.

Excluding child fields does not mean their values will be deleted. Deleting a specific child field’s value is the same as for normal fields. A null or blank must be specified.

If an entry is provided, iCIMS will try to update the group if it exists. If one is not provided, iCIMS will assume the entry is creating a new group. (The field is an entry ID or the ID of the entry in the collection group.)

Note: When attempting to add a collection containing data that is an exact duplicate of an existing collection, the update will be ignored, and a new entry will not be created.
 
Additionally, when attempting to delete data within an existing collection and replace it with an identical collection, the existing collection data will be deleted, but the new collection will not be created.

 

{
   "phones":[
    {
      "entry":23,
      "phonenumber": "212-555-1234",
            "phonetype": {
                "value": "Home"
            },
    {
      "phonenumber": "212-555-5678",
            "phonetype": {
                "value": "Work"
            },
            "default": true
    },
    {
      "entry":25,
      "delete":true
    }
  ]
}

 

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