API docs

One endpoint checks phone numbers, emails, IPs and domains. Send what you have; TrustLookup works out what it is.

Authentication

Create a key in the dashboard and send it with every request:

Authorization: Bearer lk_live_…

Look something up

GET /v1/lookup?q=…&checks=… or POST /v1/lookup with a JSON body {"q": "…", "checks": ["phone", "hlr"]}. Leave checks out to run the usual check for what you sent.

curl https://trustlookup.io/v1/lookup \
  -H "Authorization: Bearer $TRUSTLOOKUP_KEY" \
  -d q="+35799123456" -d checks="phone,hlr"

Every response has the same shape: what was detected, a one-line summary, a risk score where it applies, one result per check, and the credits it cost.

{
  "id": "lk_…",
  "type": "phone",
  "summary": "Valid mobile number in Cyprus",
  "risk": 5,
  "results": {
    "phone": { "ok": true, "credits": 1, "data": { "valid": true, "e164": "+35799123456", "line_type": "mobile", … } },
    "hlr":   { "ok": true, "credits": 5, "data": { "reachable": true, "status": "reachable", … } }
  },
  "credits_used": 6,
  "credits_remaining": 34994
}

A check that couldn’t get an answer (a timeout, a network that didn’t respond) comes back as {"ok": false, "credits": 0, "error": {…}} and costs nothing. An answer you might not like, such as an invalid number, still costs its credits.

Recent answers

TrustLookup reuses a recent answer when the same thing was checked a little while ago, so repeat lookups come back instantly. Each check in the response says "cached": true or false and when it was checked_at. A reused answer costs the same as a new one. Send fresh=true to check again now and replace the stored answer.

HLR live status	15 minutes
Email DNS check, blacklist check	1 hour
Email validation, IP intelligence, WHOIS, USDOT	24 hours
Carrier lookup, number portability, NPI	7 days
Phone validation, VIN decoder	30 days, or until the numbering-plan data is updated

Checks that couldn’t get an answer are never reused.

Checks and prices

Check	What it is	Works on	Price
`phone`	Phone validation	phone	1 credit
`carrier`	Carrier lookup Pro	phone	2 credits
`mnp`	Number portability Pro	phone	3 credits
`hlr`	HLR live status Pro	phone	5 credits
`email`	Email validation	email	1 credit
`email_dns`	Email DNS check	email, domain	Free
`ip`	IP intelligence	ipv4, ipv6	1 credit
`ip_blacklist`	Blacklist check	ipv4	Free
`whois`	WHOIS and domain age	domain, email	1 credit
`vin`	VIN decoder	vin	Free
`npi`	NPI lookup	npi	Free
`usdot`	USDOT lookup	usdot	Free

VIN, NPI and USDOT numbers look like other things, so name the check: checks=vin. Pro lookups need a paid plan. IP location and network data: IP Geolocation by DB-IP (CC BY 4.0).

Free reference tools

GET /v1/reference/area-codes/212: where a North American area code is
GET /v1/reference/countries and /v1/reference/countries/CY: calling codes and time zones
GET /v1/reference/zip/94103: city and state for a US ZIP code
GET /v1/reference/my-ip: the IP your request came from

Account and usage

GET /v1/account returns your plan, balance and when each batch of credits expires. GET /v1/usage?days=30 returns lookups and credits per day and check.

Errors

`400`	`missing_query`, `unknown_check`, `check_not_applicable`, `unrecognized_input`
`401`	`missing_key`, `invalid_key`
`402`	`insufficient_credits`: includes `required`, `available` and `upgrade_url`
`403`	`pro_required`: a Pro lookup on the free plan
`429`	`rate_limited`: wait for `Retry-After` seconds

Rate limits: 5 requests a second on Free, 50 on paid plans, higher on Scale by request. Responses carry X-RateLimit-Remaining and X-Credits-Remaining.

Webhooks (Growth and Scale)

Events: job.completed, credits.low, credits.depleted, subscription.updated. Each POST has a TrustLookup-Signature: t=…,v1=… header, where v1 is HMAC-SHA256 of t.rawBody with your endpoint’s signing secret. Answer with a 2xx within 10 seconds; failures are retried six times over about a day.

Credits

Free plans get 250 credits on the 1st of each month. Paid plans get their credits each billing period, and they roll over for three months. Top-ups on paid plans are 10,000 credits for $35, valid for a year. Credits that expire first are spent first.