Get started

Quickstart

Send a test lead through search, results and submit in five minutes with curl.

You need an API key, your affiliate id and a campaign id (see Authentication). Every call below sets icon_is_test_lead: true, so the lead runs the whole pipeline and no buyer ever receives it (see Testing).

bash

export ICON_API_KEY='<your API key>'

#1. Search

bash

curl -X POST 'https://iconroute.io/api/v1/engine/search' \
  -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",
  "lead": {
    "personal": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "[email protected]",
      "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"
  },
  "tcpa_consent": true,
  "trusted_form_cert_url": "https://cert.trustedform.com/0123456789abcdef0123456789abcdef01234567",
  "icon_is_test_lead": true
}'

The answer has your search id, icon_lead_id, and the first results in offers. Keep the icon_result_id of the result you want. If processing_done is false, more results are coming.

#2. Poll for more results

bash

curl -X GET 'https://iconroute.io/api/v1/engine/results/1e8d30bb-7c5f-41b9-8cf1-5e6b57abe999' \
  -H "Authorization: Bearer $ICON_API_KEY"

Wait poll_after_ms (about a second) between polls and stop when processing_done is true. Each answer is the full list, not only the new entries.

#3. Submit

Send the result's id and your search id, the answers to its form_fields, one of its programs and the consumer's consent. The lead itself comes from your search:

bash

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",
  "icon_is_test_lead": true
}'

A test lead answers status: "held", code: "TEST_LEAD_HELD". The same call without the test flag answers ACCEPTED or a refusal such as DUPLICATE; see Submit a lead.

#Next

Show the result's consent statement and send the consumer's decision: Consent and TCPA.
Handle every answer by its status and retryable: Errors and retries.
Stay under your limits (search: 60 per minute by default): Rate limits.

The result id api-0b7e4a2c-981234 above is only an example: always submit an id from your own search.