Get started
Authentication and API keys
Every call carries an API key issued to your affiliate account, and names your campaign and affiliate.
#API keys
An API key belongs to your affiliate account. ICON issues keys; each key can carry its own rate limits and an expiry date, and can be revoked at any time.
- Where to find them: your ICON contact issues and rotates your keys.
- Keep keys on your server. The API is server to server. Never put a key in a web page or an app.
- One key per integration makes rotation and troubleshooting easier. Ask for a new key before you revoke the old one.
#Sending the key
Send the key in the Authorization header:
http
POST /api/v1/engine/search HTTP/1.1
Host: iconroute.io
Authorization: Bearer <your API key>
Content-Type: application/jsonX-API-Key: <your API key> is accepted too. Prefer a header: a key in a URL ends up in logs.
#Campaign and affiliate on every call
The key says who you are; each search and submit also says which campaign it is for:
| 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. |
Your ICON contact gives you your affiliate id and your campaign ids. A campaign determines which offers a search covers and how your payout is set.
#When authentication fails
| HTTP | code | status | reason | When |
|---|---|---|---|---|
| 401 | AUTH_REQUIRED | invalid | Missing API key | No API key was sent. |
| 401 | AUTH_INVALID | invalid | Invalid API key | ICON does not know the key, or it was revoked or has expired. |
| 403 | FORBIDDEN | invalid | Not permitted | The campaign, offer or lead is not yours, or the request is not allowed for this key. |
None of these is retryable as is: fix the key or the ids first.