Search Results

Numbers Lookup


API Interface: HTTPS
Resource: Number Lookup
URI: https://apix.aerialink/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 that this is an add-on resource and must be a part of your pricing contract agreement prior to use. Reach out to your Aerialink Account Director for more information.

This API can be used to:

  • Perform lookups on destination numbers
  • Perform lookups on intended BYONs
  • Perform lookups on existing Aerialink leased numbers
  • Perform lookups on foreign numbers, domestic numbers - any numbers!

For instructions regarding authentication and other setup details, please see our Getting Started section.

Reading This Documentation

To help you get the most out of this guide, keep the following in mind as you read:

  • Each section of this documentation is titled with the aspect of your Aerialink Platform account connections you wish to view or change.
  • Each section includes the combined methods and URIs you can use to interact with that aspect to achieve a desired result.
  • Each section includes a list of required and/or optional parameters and in some cases, read-only parameters which are returned but cannot be changed.
  • The methods in some sections require that the actions of other sections have already been completed. These sections list these preceding actions as “Requirements” at the beginning of the section.

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.

Numbers Lookups

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


  • Aerialink Platform account
  • Access to the Numbers Lookup API enabled in your account as an add-on.

Numbers Lookup Methods

ActionMethodURI<Details & Notes
Look Up a NumberGET/numbersLook up the details of a number

Numbers Lookup Parameters

Parameters are listed below. Note:

  • Parameters not listed as Required are Optional.
  • Parameters listed as required for only some methods are optional for others.
  • Parameters listed as “Read-Only” are returned in some responses but cannot be submitted or altered.
Required forRequest Method(s)ParameterData TypeDescription
GETGETnumbersvarchar [1599]The value of this parameter is one or multiple telecommunications numbers. Please note that country code must be included. Multiple numbers should be comma delimited with the final number ending with no trailing comma. Content exceeding 1599 characters will be ignored or rejected.
GETisNumberTypeRequestbooleanPassing “true” will cause a new property named “numberType” to appear in the result.
read-onlynumberTypeThe numberType property is a string containing one the following potential values.
Type of phone number: M (mobile), L (Landline), VM (VOIP Mobile), VL (VOIP Landline). If an invalid number is given no parameter will be returned.
read-onlyguidThe globally unique identifier for this transaction or API request
read-onlymccMobile Country Code
read-onlymncMobile Network Code
read-onlyocnOperating Company directory Number (if available)
read-onlyoperatorThe registered name of the operator/carrier
read-onlyoperatorIDThe Operator Identifier (properietary)
read-onlywirelessbooleanIndicates whether the number is “wireless.” A result of “1” or “true” indicates the number is messaging-enabled. A result of “0” or “false” indicates the number is not messaging-enabled.
read-onlycountryThe registered country name for the number
read-onlycountryCodeThe country code for the requested number(s)
read-onlycountryAbbreviationThe two-letter country abbreviation (ISO 3166-1 alpha-2)
read-onlycountryUTCOffsetStartStarting timezone offset for the associated country
read-onlycountryUTCOffsetEndEnding timezone offset for the associated country
read-onlydaylightSavingTimeObserverIndicates whether a number’s associated geographic region observes Daylight Saving Time
read-onlylastUpdatedThe date of the last network query for the data
read-onlystateThe registered state of the number.*
read-onlystateAbbreviationThe two-letter state abbreviation (ANSI alpha-2)*
read-onlycityThe registered city of the number*
read-onlytimzeoneLocal timezone for the number*

* Note: Starred parameters are populated for +1-country-code (NANP) numbers only. All other numbers will return these paramaters but without a populated value.

Request: Asynchronous

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.

Response Samples

GET Response (default/JSON)

“aerialink”: {
“version”: “v4”,
“resource”: “numbers”,
“method”: “get”,
“type”: “synchronous”,
“callbackURL”: “”,
“transactions”: [{
“transaction”: {
“guid”: “abcdef-1234-abcd-5678-abcdef123456”,
“number”: “12345678910”,
“mcc”: “”,
“mnc”: “”,
“ocn”: “”,
“operator”: “EXAMPLE WIRELESS”,
“operatorID”: 1234567,
“operatorType”: “VoIP”,
“wireless”: true,
“country”: “United States of America”,
“countryCode”: 1,
“state”: “Ohio”,
“city”: “Example City”,
“timezone”: -5,
“daylightSavingTimeObserver”: true,
“validNumber”: true,
“lastUpdated”: “2020-11-11T21:32:50.961Z”

GET Response (XML)

<?xml version="1.0" encoding="UTF-8"?>
         <operator>EXAMPLE WIRELESS</operator>
         <country>United States of America</country>
         <city>Example City</city>

This page was last updated 1624650634308