API reference

Four endpoints, one key. Every response is JSON. Phone checks use 1-3 credits, or 3-5 with caller name. Email, IP and DNS checks use 1 credit. Failed or invalid results are free.

Authentication

Send your key as a Bearer token. Use POST for sensitive inputs so they do not appear in request URLs. Do not put keys in URLs.

curl "https://lookuplab.io/api/v1/phone/?number=3125550142" \
  -H "Authorization: Bearer YOUR_API_KEY"

Phone

GET https://lookuplab.io/api/v1/phone/?number=… or POST with a JSON body {"number": "…"}. Add caller_name=1 for CNAM (adds 2 credits).

{
  "data": {
    "number": "+13125550142",
    "national_format": "(312) 555-0142",
    "country": "US",
    "valid": true,
    "line_type": "mobile",
    "carrier": "T-Mobile USA",
    "city": "CHICAGO",
    "state": "Illinois",
    "ported": true,
    "ported_date": "2023-04-11",
    "lrn": "3122600000",
    "ocn": "6529",
    "caller_name": "JANE DOE"
  },
  "meta": { "charged": 3, "credits_remaining": 997 }
}

line_type is one of mobile, landline, voip, toll_free, unknown.

Email

Email checks validate syntax and domain signals. They do not verify ownership or prove that a mailbox exists.

GET https://lookuplab.io/api/v1/email/?email=…

{
  "data": {
    "email": "jane@acme.com",
    "domain": "acme.com",
    "syntax_valid": true,
    "has_mx": true,
    "mx_provider": "Google Workspace",
    "disposable": false,
    "free_provider": false,
    "role_account": false,
    "smtp": { "attempted": false },
    "valid": true,
    "reason": "deliverable_domain",
    "risk": "low"
  },
  "meta": { "charged": 1, "credits_remaining": 998 }
}

IP

GET https://lookuplab.io/api/v1/ip/?ip=…

{
  "data": {
    "ip": "8.8.8.8",
    "country": "US", "region": "California", "city": "Mountain View",
    "timezone": "America/Los_Angeles", "lat": 37.4, "lon": -122.07,
    "asn": "AS15169", "org": "Google LLC",
    "hosting": true, "proxy": false, "vpn": false, "tor": false,
    "is_anonymous": true
  },
  "meta": { "charged": 1, "credits_remaining": 997 }
}

DNS

GET https://lookuplab.io/api/v1/dns/?domain=…&check=mx|spf|dmarc|dkim&selector=…. Each check returns the parsed record and an issues array of plain-English problems.

Errors

Status	Error	Meaning
400	missing_parameter	No number, email, ip or domain given.
401	unauthorized	Missing or unknown key.
402	insufficient_credits	Balance is below the maximum reserved cost of this lookup.
429	rate_limited	Daily attempt allowance reached.

Limits and caching

Free accounts allow 200 attempts per UTC day, with a shared limit of 500 free phone attempts per day. Paid accounts allow 100,000. Invalid results count toward attempt limits but use no credits. Phone results may be cached for up to seven days and IP results for one day; repeat lookups still use the normal credit price. Use an Idempotency-Key header to replay the same operation within 24 hours without another charge. A phone request reserves up to 3 credits (5 with caller name), then refunds any difference.

MCP

Agents can call the same four tools through the MCP server at https://lookuplab.io/api/mcp.

Get a key