API reference

Duplicate pre-check

POST /api/v1/engine/dupe-check: ask whether ICON would call a lead a duplicate, before you post it.

http

POST /api/v1/engine/dupe-check

Optional. Answers one thing: duplicate_likely, true or false. No score, no matched fields. Submit always runs ICON's full duplicate check, whatever the pre-check answered.

Server to server only. The endpoint has no CORS: call it from your server, never from a web page.
Rate limit: 30 per minute per key (bursts of up to 10), separate from your other limits.
Body: at most 16 KB.

#Request

Send any of the lead's fields, raw (the same names as a lead), or hashed under hashed, or both. A hashed key wins over the same raw key. The more fields you send, the more accurate the answer.

Field	Type	Required	Description
`offer_id`	string (uuid)	—	Optional: one of your offers (for an offer-scoped policy).
`email`	string	—	—
`phone`	string	—	—
`first_name`	string	—	—
`last_name`	string	—	—
`zip`	string	—	—
`address`	string	—	—
`dob`	string	—	YYYY-MM-DD or MM/DD/YYYY.
`hashed`	object	—	—

Raw:

bash

curl -X POST 'https://iconroute.io/api/v1/engine/dupe-check' \
  -H "Authorization: Bearer $ICON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "ada.lovelace@mail.test",
  "phone": "(602) 555-2368",
  "zip": "85004",
  "last_name": "Lovelace"
}'

Hashed:

json

{
  "hashed": {
    "email": "d6117306485ed0e50afab3ac871e98f81699151f30281527d63ff5f233656c69",
    "phone": "2f83685e66d4cb4d1bcff5f422ff9b0d7ce748a6f3103269d1adad16ab2e279b",
    "zip": "918abeeaae3a90ad25f3a5e45408af4cdd71ac92accc3638461dc2f76e39cc01"
  }
}

#Hashing

hashed.<key> is the lower-case hex SHA-256 of the key's normalized form, encoded as UTF-8. Normalize first, then hash. Each example below was computed by ICON's own normalizer:

Key	Normalized form	Example
`email`	Trimmed and lower-case. At gmail.com and googlemail.com the dots and any +tag are removed from the local part and the domain is gmail.com.	`Jane.Doe+promo@GoogleMail.com` → `janedoe@gmail.com`
`phone`	The 10 US digits: no country code, no punctuation.	`+1 (602) 555-2368` → `6025552368`
`last_name`	Lower-case a–z only: accents removed (ł ø đ ð þ æ œ ß ı ħ ŧ written l o d d th ae oe ss i h t); spaces, hyphens and apostrophes dropped.	`Núñez-O'Brien` → `nunezobrien`
`zip`	The 5 digits (a +4 is dropped).	`85001-1234` → `85001`
`dob`	YYYY-MM-DD. Send birth_year with it when you hash a date of birth.	`04/07/1990` → `1990-04-07`
`birth_year`	Four digits (from a year-born answer or the date of birth).	`1990-04-07` → `1990`
`grad_year`	Four digits.	`2008` → `2008`
`ip`	The client address: the first of a forwarded list; IPv4 as a dotted quad without leading zeros; IPv6 compressed and lower-case, an IPv4-mapped address written as IPv4.	`2001:0DB8:0000:0000:0000:0000:0000:0001` → `2001:db8::1`

The SHA-256 of each normalized example above:

text

email      d6117306485ed0e50afab3ac871e98f81699151f30281527d63ff5f233656c69
phone      2f83685e66d4cb4d1bcff5f422ff9b0d7ce748a6f3103269d1adad16ab2e279b
last_name  36a69f8b745a87f4314b2dbcb8906ab78c03d4e2595f6b694f7af49b31f51242
zip        918abeeaae3a90ad25f3a5e45408af4cdd71ac92accc3638461dc2f76e39cc01
dob        8b44df2e1ab8ebe9eb4704090cf1524944141f66c7ab6dbed65391681a0d4878
birth_year a7be8e1fe282a37cd666e0632b17d933fa13f21addf4798fc0455bc166e2488c
grad_year  e5e53c784d5d49de1cabb6e904bf3380026aadcb9769775a268dd304dd9aa2df
ip         5afd19e856d1c18d17d600dfd2b5f534992333985e126c2a951047102c1ed536

Send the first name, the street address and the consent certificate raw, under their usual lead names (first_name, address, trusted_form_cert_url or universal_leadid): their matching forms are ICON's.

javascript

import { createHash } from 'node:crypto';

const sha256 = (value) => createHash('sha256').update(value, 'utf8').digest('hex');

// Normalize first (see the table), then hash.
const body = {
  hashed: {
    email: sha256('janedoe@gmail.com'),
    phone: sha256('6025552368'),
    zip: sha256('85001'),
  },
};

python

import hashlib

def sha256(value: str) -> str:
    return hashlib.sha256(value.encode("utf-8")).hexdigest()

body = {"hashed": {"email": sha256("janedoe@gmail.com")}}

#Response

json

{
  "code": "OK",
  "status": "accepted",
  "reason": "OK",
  "success": true,
  "duplicate_likely": false,
  "retryable": false
}

duplicate_likely: true means a submit of this lead would very likely be refused as DUPLICATE. false is not a promise: the submit's own check decides.

#Errors

HTTP	Meaning
400	MALFORMED_REQUEST: no usable lead field was sent (raw or hashed); INVALID_FIELD: offer_id is not a UUID.
401	AUTH_REQUIRED (no API key) or AUTH_INVALID (a key ICON does not know); status invalid.
403	FORBIDDEN: the offer_id is not yours, or this key is not permitted to use the pre-check.
404	Not found: the pre-check is not available on your account; ask your ICON contact.
405	MALFORMED_REQUEST: use POST.
413	The body is over 16 KB.
429	RATE_LIMITED (retryable): this key is over its pre-check limit. Wait the Retry-After seconds and retry.
503	UNAVAILABLE (retryable): the check could not run. Retry, or post the lead: submit runs the full check.

A 404 answers a plain {"error": "Not found"} body.