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

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.

* 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

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:

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."
    }
}