API reference

Submit a lead

POST /api/v1/engine/leads: submit a search result, or post a lead straight to an offer.

POST /api/v1/engine/leads

Delivers a lead to one offer. ICON runs its full checks again (duplicate, caps, eligibility, required fields, consent) before the lead reaches the buyer, and answers with the outcome.

Rate limit: 120 per minute per key (bursts of up to 120). Every call to this endpoint counts.

#Submitting a search result

Send the icon_result_id the consumer chose, the search it came from (search_lead_id), the program, the answers to the result's form_fields and the consumer's consent. You do not send the lead again: ICON builds the submit on the lead of the search the result came from.

Plus icon_campaign_id, icon_affiliate_id, the consent fields (Consent and TCPA) and one key per answered question. Do not send icon_lead_id on a result submit: search_lead_id links it to the search.

curl -X POST 'https://iconroute.io/api/v1/engine/leads' \
  -H "Authorization: Bearer $ICON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "icon_result_id": "api-0b7e4a2c-981234",
  "search_lead_id": "1e8d30bb-7c5f-41b9-8cf1-5e6b57abe999",
  "icon_campaign_id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "icon_affiliate_id": "3c9d8e7f-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
  "program_id": "4411",
  "api_field_military": "none",
  "tcpa_consent": true,
  "consent_button_label": "Request information"
}'

How ICON builds the submit:

• The lead, tracking and consumer IP come from your search. Any lead field you send with the submit replaces the search's value (for example a corrected phone number, or an answer the search did not have).
• Consent is not taken from the search: send tcpa_consent (and consent_button_label) with every submit, for the statement shown with that result.
• The result must belong to your API key: another affiliate's result answers 404 (error: "search_result_not_found"), even if you send a full lead. A campaign you name must be one of the result's (403, error: "result_campaign_mismatch").
• Sending the full lead still works.

Every submit is recorded as its own lead, linked to the search.

#Direct posting

When your campaign has an offer you post to directly, skip the search: send the whole lead with your campaign id, the offer id and the consumer's IP in tracking.ip_address (required).

curl -X POST 'https://iconroute.io/api/v1/engine/leads' \
  -H "Authorization: Bearer $ICON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "icon_campaign_id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "icon_affiliate_id": "3c9d8e7f-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
  "icon_offer_id": "0b7e4a2c-9d8f-4e1a-b2c3-d4e5f6a7b8c9",
  "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"
  },
  "program_id": "4411",
  "tcpa_consent": true,
  "trusted_form_cert_url": "https://cert.trustedform.com/0123456789abcdef0123456789abcdef01234567"
}'

Your ICON contact gives you the offer id, its consent statement and the questions it requires. A partner offer (one ICON calls through its own API) can only be submitted from a search result.

#Response

Accepted:

{
  "code": "ACCEPTED",
  "status": "accepted",
  "reason": "Lead accepted",
  "success": true,
  "accepted": true,
  "retryable": false,
  "icon_lead_id": "5a2c7e91-3b4d-4f6a-9c8e-2d1f0b7a6e53",
  "payout": 28,
  "message": "Lead processed successfully"
}

Refused (here, ICON already has this lead for the offer):

{
  "code": "DUPLICATE",
  "status": "rejected",
  "reason": "Duplicate - Offer",
  "source": "icon",
  "success": false,
  "accepted": false,
  "retryable": false,
  "icon_lead_id": "5a2c7e91-3b4d-4f6a-9c8e-2d1f0b7a6e53",
  "payout": 0,
  "message": "Duplicate lead"
}

The answer's icon_lead_id is the id of the lead this submit created, not your search id: store it with your own lead.

A decision (accepted or refused by ICON or the buyer) answers HTTP 200, and so do most refusals for a missing or invalid answer or consent (status: "invalid"): read status and code, not the HTTP status. PENDING (HTTP 200 or 202) is not final: the buyer has not decided yet. The reasons are standardized: Duplicate - Offer means ICON already has the lead for that offer, Duplicate - Client means the school's own system said duplicate. See Standard responses.

#Errors