Search Results

Numbers Lookup

Overview

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.


Number Lookups

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

Requirements

  • 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”
“numberType”:”VM”}
},]
}
}

GET Response (XML)

<?xml version="1.0" encoding="UTF-8"?>
<aerialink>
 <version>v4</version>
 <resource>numbers</resource>
 <method>get</method>
 <type>synchronous</type>
 <callbackURL></callbackURL>
 <transactions>
  <transaction>
      <guid>abcdef-1234-abcd-5678-abcdef123456</guid>
         <number>12345678910</number>
         <mcc></mcc>
         <mnc></mnc>
         <ocn></ocn>
         <operator>EXAMPLE WIRELESS</operator>
         <operatorID>1234567</operatorID>
         <operatorType>VoIP</operatorType>
         <wireless>true</wireless>
         <country>United States of America</country>
         <countryCode>1</countryCode>
         <state>Ohio</state>
         <city>Example City</city>
         <timezone>-5</timezone>
         <daylightSavingTimeObserver>true</daylightSavingTimeObserver>
         <validNumber>true</validNumber>
         <lastUpdated>2020-11-11T21:32:50.961Z</lastUpdated>
        <numberType>VM</numberType>
 </transaction>
</transactions>
</aerialink>

Number Deactivations Retrieval

API Interface: HTTPS
Resource: Number Deactivations
URI: https://apix.aerialink/v4/numbers/deactivations
Methods: GET
Format: .csv

This resource lets you retrieve a list of U.S. phone numbers that have been deactivated by mobile carriers. These phone numbers are no longer in service for the subscriber who used to use that number. The carriers provide this data to reduce the number of unwanted messages to numbers that have been deactivated and then reassigned to a new user. Aerialink will update the report daily as made available by the MNO carriers. These should be used periodically to remove phone numbers from your opted-in subscriber list.

You get the data for a single day, each day is about 10MB of data. Reports are available from July 15th, 2023 onward.

For more information about the compliance requirements for honoring deactivated numbers, read our Deactivated Numbers Compliance article.

Number Deactivations Methods

ActionMethodURIDetails & Notes
Retrieve Deactivated NumbersGET/numbers/deactivationsRetrieve deactivated number data including details of the number’s deactivation date and carrier name. Average number of records per file is 100k.

Number Deactivations Parameters

Each GET request will retrieve the report for a single day. You should pass in a Date parameter (in YYYYMMDD format) to indicate the report you want to retrieve.
There is only a single parameter on this request:

Required forRequest Method(s)ParameterData TypeDescription
GETdateThe request will return a list of all U.S. phone numbers deactivated on the date specified by this parameter. This date should be specified in YYYYMMDD format. Defaults to the current date.

Response Samples

Success Response

Successful results are provided as CSV formatted text. The size of the result data is 10MB or more.

Failure Response

{
    "aerialink": {
        "version": "v4",
        "resource": "numbers.deactivations",
        "method": "get",
        "type": "synchronous",
        "error": "NoSuchKey: The specified key does not exist."
    }
}