Developer Resources

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
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,
    }
  ]
}

 

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 id is provided, iCIMS will try to update the group if it exists. If one is not provided, iCIMS will assume the id is creating a new 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”:“home”
    },
    {
      “phonenumber”:“212-555-5678”,
      “phonetype”:“work”,
      “default”:true
    },
    {
      “entry”:25,
      “delete”:true
    }
  ]
}