v77

latestOpenAPI 3.1.0MITraw.githubusercontent.com2026-08-012528701.8 MB

Phone Number Lookup

Look up phone number

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

No API token scope is required to make a successful request to this endpoint.

Learn more about API scopes.

get/api/relay/rest/lookup/phone_number/{e164_number}

Path parameters

e164_numberstring required

The phone number in E.164 format.

Query parameters

includestring

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.

Response

The request has succeeded.

country_code_numberinteger

The Country code associated with the number.

national_numberstring

Number in the countries national format.

possible_numberboolean

Whether the number supplied is a possible number.

valid_numberboolean

Whether the number supplied is a valid number.

national_number_formattedstring

The E164 number formatted in national format.

international_number_formattedstring

The E164 number formatted in international format.

e164string

The number in E164 format.

locationstring

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

country_codestring

The ISO3166 alpha 2 country code associated with the number.

timezonesstring[]

The time zones associated with the number.

number_typestring

The type of number based on its area code and NPA.

Example response

{
  "country_code_number": 1,
  "national_number": "5551234567",
  "possible_number": true,
  "valid_number": true,
  "national_number_formatted": "(555) 123-4567",
  "international_number_formatted": "+1 555-123-4567",
  "e164": "+15551234567",
  "location": "Texas",
  "country_code": "US",
  "number_type": "Fixed Line or Mobile",
  "carrier": {
    "lrn": "15551234567",
    "spid": "683X",
    "ocn": "12345",
    "lata": "99999",
    "city": "Aberdeen",
    "state": "WA",
    "jurisdiction": "indeterminate",
    "lec": "Verizon",
    "linetype": "landline"
  },
  "cnam": {
    "caller_id": "John Smith"
  }
}