▣ DATA VALIDATION · GEOLOCATION

Phone Carrier Lookup API

What it does

Phone Carrier Lookup tells you which carrier a phone number belongs to, along with its geographic region, time zones, and number type.

Send a phone number in the number query parameter, and optionally set country if you need help interpreting the number in a specific country. The response returns the normalized number, plus carrier, region, timezones, and number_type when they are available.

Use it to validate contact data during signup flows, route support or SMS workflows, or enrich a lead record with phone metadata before storing it. It is a straightforward lookup for developers who need to understand where a number is based and how it is classified without building their own numbering-plan logic.

Because the lookup can return null values for carrier or region, it fits well in systems that need to handle partial results cleanly and make a decision based on whatever metadata is available.

GET

Look up carrier name, geographic region, and timezones for a phone number

http://localhost:8080/dosvak/phone-carrier-lookup

QUICKSTARTGUIDE

Quickstart

Look up carrier details for a phone number by passing the required number query parameter.

curl -X GET "http://localhost:8080/dosvak/phone-carrier-lookup?number=%2B14155552671" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with these top-level fields: number (string), region (string or null), carrier (string or null), timezones (array of string), and number_type (string).

{
  "number": "+14155552671",
  "region": "California",
  "carrier": "AT&T",
  "timezones": ["America/Los_Angeles"],
  "number_type": "mobile"
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Looks up details for a phone number and returns a JSON object containing the number, its geographic region, carrier, timezones, and number type.

Query Parameter(s)

Attribute	Type	Mandatory	Description
number	String	Yes	Phone number to look up.
country	String	No	Country code to use for lookup. Default: `US`.

Response

Returns a JSON object with number, region, carrier, timezones, and number_type fields. The region and carrier fields are nullable strings, timezones is an array of strings, and number_type is a string.

Parameter	Type	Mandatory	Description
number	String	No	The phone number returned by the lookup.
region	String	No	Geographic region for the phone number, or null if unavailable.
carrier	String	No	Carrier name for the phone number, or null if unavailable.
timezones	String Array	No	Timezone names associated with the phone number.
number_type	String	No	The phone number type returned by the lookup.

Query parameters

Name

Type

Description

numberREQUIRED

string

—

countryOPTIONAL

string

—

DEFAULT US

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.