Guides and reference

Field dictionary

The lead fields ICON reads, where it stores them, the other names it accepts and the values it stores.

Send these fields and values and every offer receives what it expects. The tables are generated from ICON's field value standards.

#Shape of a lead

Send the lead nested, as ICON stores it:

json

{
  "lead": {
    "personal": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada.lovelace@mail.test",
      "phone": "6025552368",
      "date_of_birth": "1990-04-07"
    },
    "address": {
      "address_line_1": "123 N Main St",
      "city": "Phoenix",
      "state": "AZ",
      "zip_code": "85004"
    },
    "education": {
      "education_level": "bachelors",
      "high_school_graduation_year": "2008",
      "start_timeline": "1_3_months",
      "learning_preference": "online"
    },
    "background": {
      "military_affiliation": "none",
      "us_citizen": "yes"
    }
  },
  "tracking": {
    "ip_address": "203.0.113.9",
    "subid": "pub-42",
    "subid2": "creative-7",
    "utm_source": "partner",
    "utm_medium": "email",
    "utm_campaign": "fall-enrollment"
  }
}

Flat keys are accepted too (the Also accepted column): email, phone, zip, dob, … . Prefer the nested form.

#Identity and control fields

Field	Type	Required	Description
`icon_campaign_id`	string	required (search + submit)	ICON campaign ID (UUID) of the campaign this request is for. Required on every search and every submit: ICON never picks a campaign for you.
`icon_affiliate_id`	string	required (search + submit)	Your ICON affiliate ID (UUID). Required on every search and every submit, and must be the affiliate your API key belongs to. ICON records the affiliate from the key; this value is only checked against it.
`icon_offer_id`	string	required for direct posting	The ICON offer id (UUID). Required when you post a lead straight to an offer; taken from the result when you submit an icon_result_id.
`icon_lead_id`	string	optional (submit)	The icon_lead_id ICON returned for a lead you posted directly: send it when you retry that post, so ICON recognises the lead. A request that would change a submitted lead is refused (403). Not used on a result submit (send search_lead_id).

#Contact, address and formatted fields

Send each in the format shown.

Field	Stored at	Also accepted	Format
high_school_graduation_year	`lead.education.high_school_graduation_year`	`high_school_graduation_year`, `grad_year`	Four digits, e.g. 2012.
email	`lead.personal.email`	`email`	An email address.
phone	`lead.personal.phone`	`phone`	The 10-digit US number, digits only (e.g. 6025552368).
first_name	`lead.personal.first_name`	`first_name`, `firstname`	Text.
last_name	`lead.personal.last_name`	`last_name`, `lastname`	Text.
address_line_1	`lead.address.address_line_1`	`address`, `address_line1`	The street line.
address_line_2	`lead.address.address_line_2`	`address2`, `address_line2`	Unit / apartment line.
city	`lead.address.city`	`city`	Text.
state	`lead.address.state`	`state`	The two-letter US state code. Values: `AL`, `AK`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DE`, `FL`, `GA`, `HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MD`, `MA`, `MI`, `MN`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`, `WA`, `WV`, `WI`, `WY`, `DC`, `AS`, `GU`, `MP`, `PR`, `VI`, `UM`
zip_code	`lead.address.zip_code`	`zip`, `zip_code`	The 5-digit ZIP.
date_of_birth	`lead.personal.date_of_birth`	`dob`	YYYY-MM-DD.
age	`lead.personal.age`	`age`	Whole number of years.
year_born	`year_born`	—	Four digits.
ip_address	`tracking.ip_address`	`ip`	The consumer's own public IPv4 or IPv6 address (not your server's). Required from affiliates.
UTM parameters	`tracking.utm_source`, `tracking.utm_medium`, `tracking.utm_campaign`, `tracking.utm_content`, `tracking.utm_term`	`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`	Text, trimmed; case is kept.
Click ids and sub ids	`tracking.gclid`, `tracking.gbraid`, `tracking.wbraid`, `tracking.fbclid`, `tracking.msclkid`, `tracking.ttclid`, `tracking.click_id`, `tracking.subid`, `tracking.subid2`, `tracking.subid3`, `tracking.subid4`, `tracking.subid5`	`gclid`, `fbclid`, `msclkid`, `click_id`, `subid`, `subid2`, `subid3`, `subid4`, `subid5`	Text, trimmed; case is kept.

#Answers with fixed values

Send one of the listed values, exactly as written.

Field	Stored at	Also accepted	Values
rn_license	`lead.background.rn_license`	`rn_license`	`rn`, `lpn_lvn`, `no`
military_affiliation	`lead.background.military_affiliation`	`military_affiliation`	`none`, `affiliated`, `active_duty`, `veteran`, `spouse_dependent`
us_citizen	`lead.background.us_citizen`	`us_citizen`	`yes`, `no`
has_internet_access	`lead.background.has_internet_access`	`has_internet_access`	`yes`, `no`
teaching_certificate	`lead.education.teaching_certificate`	`teaching_certificate`	`yes`, `no`
currently_enrolled	`currently_enrolled`	—	`yes`, `no`
education_level	`lead.education.education_level`	`education_level`	`no_hs_diploma`, `ged`, `high_school`, `some_college`, `associates`, `bachelors`, `masters`, `doctorate`
start_timeline	`lead.education.start_timeline`	`start_timeline`, `start_date`	`immediately`, `1_3_months`, `4_6_months`, `7_12_months`, `over_1_year`, `not_sure`
learning_preference	`lead.education.learning_preference`	`learning_preference`	`online`, `campus`, `either`
gender	`lead.personal.gender`	`gender`	`female`, `male`

#Questions an offer adds

An offer can ask more than the fields above (a program, a licence, a school-specific question). Those come with each result as form_fields: send each answer on submit under the question's name. See Results.

Send the values exactly as listed. A value ICON does not recognise is kept as sent, never guessed; an offer that needs a recognised value refuses it as INVALID_FIELD with the field named.