Skip to main content

Phone Number Lookup

This endpoint allows you to look up validity and formatting information about a number. You can optionally lookup additional information about the number such as carrier and caller ID data.

Permissions

The API token must include the following scopes: Numbers.

Path Parameters
e164_number string REQUIRED

Number in E.164 format.

Example: +15551234567

Query Parameters
include string[]

Possible values: [carrier, cnam]

Further number information to include in the response, some of which are billable. You can specify:

  • carrier: Lookup full carrier information for the number.
  • cnam: Lookup Caller ID information for the number.

Separate multiple values with a comma: include=carrier,cnam.

Adding include=carrier to your request will do a live lookup to determine the current carrier information about this number. This includes more accurate information about what type of number as well as location. Only valid for numbers with a +1 country code.

Adding include=cnam to your request will do a live lookup to determine the current caller ID information about this number. Only valid for numbers with a +1 country code.

Example: carrier,cnam

Responses
200

OK

Schema OPTIONAL
country_code_number number OPTIONAL

The Country code associated with the number

national_number string OPTIONAL

Number in the countries national format.

possible_number boolean OPTIONAL

Whether the number supplied is a possible number. For example, in the United States +15551234567 is a possible number, but it is not a valid number.

valid_number boolean OPTIONAL

Whether the number supplied is a valid number.

national_number_formatted string OPTIONAL

The E164 number formatted in national format.

international_number_formatted string OPTIONAL

The E164 number formatted in international format.

e164 string OPTIONAL

The number in E164 format.

location string OPTIONAL

The location of the number based on its area code and NPA.

country_code string OPTIONAL

The ISO3166 alpha 2 country code associated with the number

timezones string[] OPTIONAL

The time zones associated with the number

number_type string OPTIONAL

The type of number based on its area code and NPA. For more detailed record of number type, include carrier details in the request.

carrier object OPTIONAL

Adding include=carrier to your request will do a live lookup to determine the current carrier information about this number. This includes more accurate information about what type of number as well as location.

lrn string OPTIONAL

The LRN associated with the number

spid string OPTIONAL

The Service Profile Identifier associated with the number

ocn string OPTIONAL

The Operating Company Number associated with the number

lata string OPTIONAL

The Local Access and Transport Area number associated with the number

city string OPTIONAL

The City associated with the number

state string OPTIONAL

The State/Province/Region associated with the number

jurisdiction string OPTIONAL

The Jurisdiction associated with the number

lec string OPTIONAL

The LEC or Carrier of the number.

linetype string OPTIONAL

The type of line the number is. Generally either wireless or landline

cnam object OPTIONAL

Adding include=cnam to your request will do a live lookup to determine the current caller ID information about this number.

caller_id string OPTIONAL

The caller ID associated with the number.