Phone Number Lookup

Look up phone number

Changed on

Returns validity and formatting information for any supplied E.164 phone number, with optional carrier and caller-name data. Use it to normalize or enrich a number before other workflows; it neither searches purchasable inventory nor returns numbers owned by the project. Use Search phone numbers or List phone numbers for those jobs.

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}

Request

  • Base URL
    https://{Your_Space_Name}.signalwire.com
  • URL
    https://{Your_Space_Name}.signalwire.com/api/relay/rest/lookup/phone_number/{e164_number}
  • Auth
    HTTP basic

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": {
    "ocn": "12345",
    "lata": "99999",
    "city": "Aberdeen",
    "state": "WA",
    "jurisdiction": "indeterminate",
    "lec": "Verizon",
    "linetype": "landline"
  },
  "cnam": {
    "caller_id": "John Smith"
  }
}

Changes

  • 5c743456ec76Revision changes
    • warning

      removed the optional property ///// from the response with the status

    • warning

      removed the optional property ///// from the response with the status

Some revisions have not been checked yet.