API reference

Four endpoints, one key. Every response is JSON. Every successful lookup costs one credit unless noted; failed or invalid lookups are free.

Authentication

Send your key as a Bearer token. Query string api_key also works for quick tests.

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 (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": 1, "credits_remaining": 999 }
}

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

Email

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": true, "code": 250, "accepted": true },
    "valid": true,
    "reason": "mailbox_accepted",
    "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 zero. Top up or upgrade.
429	rate_limited	Over 1,000 requests a minute.

Limits and caching

1,000 requests a minute per key. We cache phone results for seven days and IP results for one day, so repeated lookups of the same input inside the window are served from cache and still count as one credit each.

MCP

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

Get a key