API Documentation

Global phone intelligence in one call — carrier, country, number type, formatting and timezones.

Authentication

Every request to /api/v1/lookup requires a bearer token. Generate one in your dashboard.

Authorization: Bearer nsk_live_XXXXXXXXXXXX

Endpoints

GET/api/v1/lookup?phone=+14155551234

POST/api/v1/lookup— body {"phone":"+1..."} or {"phones":["+1...",...]} (max 50)

Parameters

Field	Type	Notes
phone	string	E.164 recommended. 6–20 digits.
phones	string[]	POST only. Up to 50.

Response

{
  "phone": "14155551234",
  "result": {
    "is_valid": true,
    "country_code": 1,
    "region_code": "US",
    "carrier": "AT&T",
    "location": "California",
    "number_type": "MOBILE",
    "formatted_international": "+1 415-555-1234",
    "formatted_national": "(415) 555-1234",
    "formatted_e164": "+14155551234",
    "time_zones": ["America/Los_Angeles"]
  }
}

Error codes

Status	Code	Meaning
400	invalid_phone	Phone number missing or malformed.
401	unauthorized / invalid_key	Missing or unknown API key.
403	key_disabled / key_expired	Key was revoked, disabled, or past its expiration date.
413	batch_too_large	Batch exceeds 50 numbers.
429	rate_limited	Too many requests. Slow down or upgrade.
500	internal_error	Something went wrong on our side.
502	upstream_error	Upstream carrier database returned an error.
504	upstream_timeout	Upstream took too long to respond.

Code samples

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://numscope.lovable.app/api/v1/lookup?phone=%2B14155551234"