Carrier Lookup API Docs

Would you like to perform a carrier lookup by phone number? Now you can. The Club Texting Carrier Lookup API service allows you to automatically determine the carrier of any mobile number. To use this service, please contact us, specifying your need for the Carrier Lookup Service. We will create a separate lookup account on your behalf. Our system will keep track of how many numbers were looked up; each lookup is billed at 1 cent.

Carrier information, including ported numbers, is updated in real time. The data our lookup service returns is the same data the carriers rely upon to route messages in and out of their own networks.

We offer both HTTP and REST Carrier Lookup APIs. Please make sure that you are reading the correct documentation for the API that you are using to connect to Club Texting's Carrier Lookup Service. Both APIs return carrier codes from the table at the bottom of this page (View List).

REST Carrier Lookup API

Our REST Carrier Lookup API can return both JSON and XML results. You may specify the format you prefer in your request. Looking for Code Samples? Choose your language from the navigation bar to the left.

Carrier Lookup

Returns the wireless carrier of a valid mobile phone number (US & Canada)

URL

https://app.clubtexting.com/sending/phone-numbers/phone-number?format=format

Format & Method

Format can be either XML or JSON
HTTP Method must be GET

Parameters

User (Required) Your Club Texting username
Password (Required) Your Club Texting password
PhoneNumber (Required) 10 Digit Phone Number

Return Values

PhoneNumber Phone Number from the request
CarrierName Carrier name the phone number belongs to

HTTP Status Codes

200 Success
401 Unauthorized - Authentication credentials are missing or incorrect
403 Forbidden - Request is not valid. An accompanying error message explains why.
500 Internal Server Error - Something is broken. Please create a support ticket.

Sample Error Responses

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Status>Failure</Status>
    <Code>401</Code>
    <Errors>
        <Error>Authorization Required</Error>
    </Errors>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Status>Failure</Status>
    <Code>403</Code>
    <Errors>
        <Error>PhoneNumbers: '(123)45-67' contains characters which are not digits</Error>
    </Errors>
</Response>

Successful Call & Response Samples

XML Example And Response:

curl "https://app.clubtexting.com/sending/phone-numbers/2345678910?User=winnie&Password=the-pooh&format=xml"
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Status>Success</Status>
    <Code>200</Code>
    <Entry>
        <PhoneNumber>2345678910</PhoneNumber>
        <CarrierName>ATTUS</CarrierName>
    </Entry>
</Response>

JSON Example And Response:

curl "https://app.clubtexting.com/sending/phone-numbers/2345678910?User=winnie&Password=the-pooh&format=json"
{
    "Response":{
        "Status":"Success",
        "Code":200,
        "Entry":{
            "PhoneNumber":"2345678910",
            "CarrierName":"ATTUS" 
        }
    }
}

HTTP Carrier Lookup API

A request for a page using the structure shown below is all that is needed for you to lookup the carrier of a mobile number using the Club Texting Network Lookup Service. The endpoints for these HTTP requests is https://app.clubtexting.com/api/lookup for HTTPS (SSL).

HTTP/1.1 is enabled so, if sending multiple packets, the TCP/IP connection should be kept open between requests. Requests should be sent as a HTTP GET using the parameters listed below.

Example of Carrier Lookup API Usage:

< ? php
$ch = curl_init(“https://app.clubtexting.com/api/lookup”);
curl_setopt($ch, CURLOPT_GET, 1);
curl_setopt($ch, CURLOPT_GETFIELDS, “user=myusername&pass=mypassword&phonenumber=2345678901");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
$data = curl_exec($ch);
print($data); /* result of API call*/
?>

Code Samples For The Carrier Lookup API In Other Languages


Parameters for requests

Parameters (may be passed via GET and values must be properly URL encoded)

Several parameters are common to all message types, and should be included in the HTTP request regardless of the specific method being invoked. Note that the user, pass and phonenumber parameters are required. Details of these parameters are as follows:

user Username of the account to send through
pass Password
phonenumber MSISDN of the message recipient (eg 2345678901). No leading "+" or “1” is required

The following example shows the HTTP request that is understood by the Club Texting Network Lookup Service:
https://app.clubtexting.com/api/lookup?user=myusername&pass=mypassword&phonenumber=2345678901

Parsing simple text response (default response)

The meaning of the response received is:

Value Description
<network> Carrier that the mobile number belongs to. See Carrier Codes for possible values.
UNKNOWN Unrecognized carrier. Please contact us to extend coverage.
FAILURE Lookup Failed Due to Inaccurate Mobile Number

Provider name is returned if lookup is successful. If it is not successful, a number is returned by the script as displayed in the table below. Where the following table contains explanations of certainty codes


Certainty Value
Description
-1 Invalid Username or Password
-2 Invalid Phone Number Format
-3 Insufficient Credits
-4 Lookup Error. The customer should wait a few seconds and reattempt their lookup.


Comprehensive List of US Providers
ACS Wireless ACSUS
Alltel ALLTELUS
RINA/All West Wireless ALLWESTUS
EKN/Appalachian Wireless APPALACHIANUS
Arch Wireless ARCHWIRELESSUS
AT&T Wireless ATTUS
Bluegrass Cellular BLUEGRASSUS
Boost USA BOOSTUS
Cellcom CELLCOMUS
Cellular South CELLULARSOUTHUS
Centennial CENTENNIALUS
Central Wireless CENTRALUS
Amerilink CHOICEUS
Cincinnati Bell CINBELLUS
AT&T (Formerly Cingular Wireless) CINGULARUS
Cox Communications COXUS
Cricket Communications CRICKETUS
RINA/CTC Telecom-Cambridge CTCUS
Dobson DOBSONUS
RINA/Snake River PCS EAGLEUS
ECIT - Cell One of East Central IL ECITUS
Edge Wireless EDGEUS
Element Mobile ELEMENTUS
RINA/FMTC-Farmers Mutual Telephone Co. FARMERSMUTUALUS
GCI Communications GENERALCOMUS
RINA/Silverstar GOLDSTARUS
Immix Wireless/PC Management IMMIXUS
Inland Cellular INLANDUS
Iowa Wireless IOWAWIRELESSUS
Illinois Valley Cellular IVCUS
Metrocall Wireless METROCALLUS
Metro PCS METROPCSUS
Midwest Wireless MIDWESTUS
Nex-Tech Wireless NEXTECHUS
North Coast PCS NORTHCOASTUS
nTelos NTELOSUS
RINA/Nucla-Naturita Telephone Co. NUCLANATURITAUS
Pacific Bell     PACBELLUS
Plateau Telecom PLATEAUUS
Pocket Wireless     POCKETUS
Revol REVOLUS
RCC/Unicel RURALCELUS
RINA/South Central SOUTHCENTRALUTAHUS
South Canaan Cell SOUTHCANAANUS
Southern Bell SOUTHWESTBELLUS
Sprint PCS SPRINTUS
Suncom SUNCOMUS
RINA/Syringa Wireless SYRINGAUS
Thumb Cellular THUMBUS
T-Mobile USA TMOBILEUS
Triton PCS TRITONPCSUS
RINA/UBET UNITAHBASINUS
United Wireless UNITEDWIRELESSUS
US Cellular USCELLULARUS
Verizon Wireless VERIZONUS
Viaero Wireless VIAEROUS
Virgin USA VIRGINUS
West Central Wireless WCENTRALUS
Western Wireless WESTERNWUS


Comprehensive List of Canadian Providers
Fido FIDOCA
Bell Mobility BELLCA
Wind Mobile WINDCA
Telus TELUSCA
SaskTel SASKTELCA
Virgin Canada VIRGINCA
MTS Canada MTSCA
Rogers ROGERSCA
Videotron VIDEOTRONCA

Get started for free!

Sign up now