About the Number Lookup HTTP API Reference

The Number Lookup HTTP API reference contains details about available API parameters and how to interpret incoming responses. We divide the information into the following sections:

  • Number Lookup Endpoint – A list of available endpoints for this API. This includes the methods you can use with them. This section also provides request and response parameters.
  • GSM Error Codes – Review the error codes that occur when a number is on a 2G network.
  • Status Codes – Status codes that tell you what happened with your number lookup request.

If you are looking for the marketing page about Number Lookup, see here.

Number Lookup HTTP API Endpoint

The Number Lookup API uses the following endpoint for POST requests:


If you use the API with GET requests, requests take the form of:


For either type of request, the API returns JSON by default. If you want to specify JSON or XML for the response, add .json or .xml to the end of the request endpoint. For example:

Request Parameters

Available request parameters for the Number Lookup HTTP API include:

Parameter Data Type Required Description
msisdn string yes MSISDN stands for Mobile Station International Subscriber Directory Number. The MSISDN provides the number lookup destination address. The number must be given in MSISDN format – no leading zero or plus sign ‘+’. Include the country prefix and number with no special characters or leading zeroes. For example: 49123456789
key string yes This is the API key for your account.

Response Parameters

Parameter Data Type Description
msisdn string MSISDN stands for Mobile Station International Subscriber Directory Number. The API returns it with a ‘+’ in front.
mnc string The API returns the Mobile Network Code as a two or three digit number.
mcc string The API returns the Mobile Country Code as a three digit number.
cost decimal The cost of the lookup request.
ported boolean This is information about the portability status of the MSISDN. false means not ported. true means ported.
portedNetwork Network object If the API returns true for ported, it also returns this network object. This object provides details about the network the MSISDN was ported to.

Parameter Data Type Description
networkName string The name of the network.
countryName string The name of the country.
countryPrefix string The international prefix of the country.
roaming boolean Provides information on the roaming status of the MSISDN (‘false’ in the home network, ‘true’ in roaming).
originalMnc string Information about the original network the number was ported from given as an MNC.
originalNetwork Network object If ported returned false, the original network contains the information about the current network. If ported returned true, the original network contains information about the network the number was ported from.
roamingMcc string Information about the roaming country given as the MCC.
roamingMnc string Information about the roaming network given as the MNC.
roamingNetwork Network object Information about the network the number is roaming.
msc string Provides the Global Title of the Mobile Switching Center (the serving network node)
imsi string Provides the International Mobile Subscriber Identity. This field uniquely identifies the user of a mobile network.
absent boolean Informs you of the status of the user at the time of the lookup request (‘false’ if the subscriber is available, ‘true’ if the subscriber is absent)
gsmcode number Returns the GSM error code giving detailed information.
date string UTC date and time when the result was created. The API returns the date in ISO 8601 format. For example: ‘2015-02-14T13:17:53Z’
response number The response code gives further information about the state of the lookup request.

GSM Error Codes

Global System for Mobiles (GSM) is a standard developed by the European Telecommunications Standards Institute (ETSI). The standard describes protocols for second-generation (2G) digital cellular networks used by mobile devices such as mobile phones and tablets.

If a number is on a 2G network, the Number Lookup API returns a GSM code detailing the status of the number. The codes include:

GSM Error Code Description
0 No error
1 Unknown subscriber
2 Unknown subscriber – NR changed
5 Unidentified subscriber
6 Absent subscriber for SM
7 Unknown equipment
8 Roaming not allowed
9 Illegal subscriber
10 Bearer service not provisioned
11 Teleservice not provisioned
12 Illegal equipment
13 Call barred
21 Facility not supported
27 Absent subscriber
28 Incompatible MS terminal error
31 Subscriber busy for SMS MT
32 Equipment failure
33 MS memory capacity exceeded
34 GSM system failure
35 GSM Data Error – data missing
36 GSM Data Error
45 Subscriber busy
100/101 Internal equipment error
103/104/105 Unspecified GSM error
150/151 Request timeout

Status Codes

This section provides status and error codes. You can use these to determine if your request was successful or diagnose a problem.

Response Code HTTP Status Code Description Reason
0 200 Success The lookup was successfully executed.
1 500 Unknown Error An undocumented error occurred.
2 401 Unauthorized Missing or invalid credentials
3 200 Insufficient funds Refused due to insufficient funds
4 412 Not allowed Lookup type not allowed
5 200 Invalid or no MSISDN Not a properly formatted number (not MSISDN), or no input number provided
6 200 Not a mobile MSISDN