Numbers Lookup


API Interface: HTTPS
URI: /v4/numbers
Methods: GET
Response Schemas: JSON (default), XML

The Numbers Resource provides profile and service provider data for any telephone number (mobile, landline, satellite) operating on an active network. Subscribers periodically port numbers between networks and operators periodically modify routing data. Operators in the United States, Canada, and many international countries support Mobile Number Portability (MNP). A current and accurate number profile is required to ensure successful routing and delivery of messages or voice communications.

Note: MVNOs (Mobile Virtual Network Operators) are not listed in the Numbers lookup database (with a few exceptions) as operators. An MVNO may have one or more host operators listed as network operator. (ex: MVNO Straight Talk has four host operators—AT&T, Verizon, Sprint, T-mobile—not to be confused with parent company Tracfone Wireless/América Móvil) A number lookup could return any one of the multiple host operators as the operator value.

For a reference listing of operator names, types, countries and ID numbers, see our Number Operator Reference Directory.

Response Schema

Aerialink supports both JSON and XML response schemas, however the default response schema is JSON. If you wish to receive your response schema in XML or explicitly set the response schema to JSON, follow these examples as you construct your complete request URL.

(defaults to JSON automatically)

(explicitly sets the response to a JSON schema, same as default)

(sets the response to an XML schema)

Method [GET] : Look Up a Number

This method is queries and returns the details of the numbers provided in your request parameters. The request is initiated by your application.


The available request parameters for this resource and method are listed below and should be sent form-post.

Required Parameters

  • numbers [varchar(1599)]
    The value of this parameter is one or multiple telecommunications numbers. If more than one number is provided they should be comma delimited with the final number ending without a comma trailing. A number represents a mobile, land-line, MDN, MSDN, or any term synonymous with a telecommunications number associated with a device operating on a telecommunications network. A maximum of 100 numbers or maximum content length of 1,599 is allowed. Anything beyond this will be ignored or the request may be rejected.

Optional Parameters

  • cache [integer] : default = 0
    0 = false; Returns the current most recently updated data from the network, if available.
    1 = true; Returns the last cached copy of the data, if available. If no cached copy is available a current copy will be provided.

  • callbackURL [string(100)]
    A callback URL can be provided which enables the response to be delivered as a separate POST request following the original data request. In this scenario the original request will receive a response with the associated transaction GUID which can be related to the callback transaction GUID when that request has been completed.

Response (Synchronous)

Response Properties

The parameters or elements returned in the response to an API request.

  • guid : The globally unique identifier for this transaction or API request
  • numbers : The requested number
  • mcc : Mobile Country Code
  • mnc : Mobile Network Code
  • ocn : Operating company directory number (if available)
  • operator : The registered name of the operator/carrier
  • operatorID : The Operator Identifier (proprietary)
  • operatorType : The friendly description of the operator type
  • wireless : [true or false] Indicates whether the number is of the type wireless
  • country : The registered country name for the number
  • countryCode : The country code for the requested number(s)
  • countryAbbreviation : The two-letter country abbreviation (ISO 3166-1 alpha-2)
  • countryUTCOffsetStart : The starting timezone offset for the associated country.
  • countryUTCOffsetEnd : The ending timezone offset for the associated country.
  • daylightSavingTimeObserver : Indicates whether a number’s associated geographic region observes Daylight Saving Time
  • validNumber : A given number’s validity (via true or false)
  • callbackURL : (If provided in the request) The confirmation of the callback URL where the callback request will be sent.
  • lastUpdated : The date of the last network query for the data.

Additional Parameter Values for Country Code +1
Telephone numbers that are within the country code 1 will return these additional values:

  • state : The registered state of the number
  • stateAbbreviation : The two-letter state abbreviation (ANSI alpha-2)
  • city : The registered city of the number
  • timezone : Local timezone for the number

All other telephone numbers will return these parameters but without a value.

Response Schema

JSON Format(default schema)

 "aerialink": {

XML Format

<?xml version="1.0" encoding="UTF-8"?>

Request (Asynchronous)

  • Note: Callback-only.

Aerialink expects to receive an HTTP status code of 200 from your application server which confirms your receipt of the HTTP POST. If we do not receive this HTTP status code our network will continue to retry the callback to your application until the pre-defined expiration period comes to pass.

This page was last updated 1516820502000