Number Portability Lookup HLR HTTP API
Example code for using the Number Portability Lookup API is available for programmers using Java, Perl, PHP, and AGI.
We also have plug-and-play scripts to integrate carrier lookups into your Asterisk dialplan - no coding required!
API Details - v3.32
Introduction to the API
Our API (Application Programming Interface) is designed to make it easy to integrate our number portability lookup service into your own application, with the minimum amount of additional programming.
Connectivity to the service
https://api.numberportabilitylookup.com/npl
There is a maximum of 100 numbers per request, and a maximum of five concurrent connections per account unless agreed otherwise. Note that realtime SS7/MAP or other lookups take time to process, so a large batch of numbers may take a while to process and return, however, responses will be streamed over the HTTP response as they become available.
Important Note / Feb 2025: While alternative API endpoints have been available in the past, these should be considered deprecated at this time. Please ensure all traffic is using the api.numberportabilitylookup.com/npl endpoint to avoid possible future service interruptions if the older API endpoints are decommissioned.
Performing an HLR Lookup
In order to perform an HLR query on one or more mobile numbers, pass the following parameters:
user | Your account username |
pass | Your account password |
msisdn | The number(s) to look up in E.164 format. Separate multiple numbers with commas |
format | Use format=json for the most comprehensive response. If omitted, the system will revert to a legacy CSV format with basic data points for compatibility with older API clients. New integrations should always use the 'json' format. |
msc | Pass msc=1 to request serving MSC address (if feature is enabled on your account), otherwise omit.
Note: Querying the serving MSC address is increasingly blocked due to its use in SS7 messaging fraud. Please contact us if you have a legitimate need for this data field and we can confirm availability for the networks you need. |
Example Request:
https://api.numberportabilitylookup.com/npl?user=bob&pass=123&msisdn=447788450450,447810701702&format=json
Number Formatting
Numbers should be specified in the standard E.164 international format. i.e. Country Code, and National Significant Number without National prefixing if any exist. The leading '+' symbol is not required by our service. Example: UK 07788 450 450 -> 447788450450 Example: USA 704 451 8989 -> 17044518989 Example: AUS 0449100123 -> 61449100123
If you need help on how to format a number for a specific country, please [ Contact us ].
Errors which could prevent your HLR lookup from running:
If there is a problem that prevents our system from starting to process your HLR lookup, your account balance will not be charged for the API call, and you'll receive a FAIL code:
FAIL Authentication required | The user and pass fields are required. See above. |
FAIL Invalid password | The supplied user and pass were not correct. |
FAIL No numbers | You didn't pass any numbers to lookup. The msisdn field is required. |
FAIL Request too long | You tried to lookup more than 100 numbers. |
FAIL Insufficient credit | Your account balance is too low. Please add funds. |
FAIL Connection limit | You have more simultaneous connections than allowed on your account (default 5). |
FAIL Daily limit | You have exceeded your soft daily limit. You can change this in your online account. |
FAIL Unsupported region | You attempted to lookup a number in a country other than those allowed on your account. |
FAIL Account locked | There is a problem with your account. Contact support. |
FAIL System Unavailable | The service is undergoing maintenance. Please try later. |
Example Responses
If the API response does not begin with the string FAIL, you should attempt to parse it as JSON per the structure below:
Example JSON Format Response
You'll receive a JSON array containing a data block for each MSISDN queried.
[
{
"countrycode":"44",
"countryiso":"GB",
"countryname":"United Kingdom",
"errorcode":0,
"errortext":"OK",
"imsi":"234158341040126",
"localformat":"07788 450450",
"mcc":"234",
"mnc":"15",
"msc":"44778",
"msisdn":"447788450450",
"operatorname":"Vodafone",
"originalmcc":"234",
"originalmnc":"15",
"originaloperatorname":"Vodafone",
"plmn":"23415",
"ported":false,
"reachable":true,
"transactioncost":1.20,
"validnumber":true
}
]
Example Legacy CSV Format Response
If you did not pass format=json you'll receive our legacy CSV API response as shown below:
QUERYOK
447788450450 23415,234158341040126,44778
ENDBATCH
The fields provided are: number mcc+mnc,imsi,msc
No other data points are available when using this format. We recommend using format=json for all new integrations.
Description of data fields contained in response
GSM / Worldwide HLR Query Response fields:
countrycode | Country code of number's home country |
countryiso | ISO 3166 country code of number's home country |
countryname | Name of number's home country |
errorcode | Error number if any error, otherwise 0 |
errortext | Description of the error code (otherwise "OK") |
imsi | International mobile subscriber ID of the subscriber (see note below) |
landline | Whether the number is a landline number (true or false) |
lrn | Location routing number for PSTN calls (NANP) |
localformat | Phone number formatted as it would be written in its home country |
mobile | Whether the number is a mobile number (true or false) |
mcc | GSM Mobile country code of the home network |
mnc | GSM Mobile network code of the home network |
msc | Mobile switching centre currently serving this number (if supported and enabled) |
msisdn | Mobile number to which this query pertains |
numbertype | Type of number ("MOBILE","LANDLINE","VOIP", or "TOLLFREE") |
ocn | Operating carrier number for NANP numbers |
operatorname | Name of the home network operator |
originalmcc | MCC of the original operator (if ported) |
originalmnc | MNC of the original operator (if ported) |
originalcarrier | Name of the original carrier (if ported) |
originaloperatorname | Name of the original operator (if ported) |
plmn | Public land mobile network code of home network (mcc+mnc) |
ported | Whether the number has been ported (true or false) |
reachable | Whether the number is in coverage and reachable (true, false, or "undetermined") META |
spid | Service Profile ID |
timezone | Timezone where the number is registered |
transactioncost | Cost of this lookup in credits (eg 1.00) |
userbalance | Remaining balance in user account after transactioncost was deducted |
validnumber | Whether the number is a valid subscriber (true, false, or "undetermined") META |
IMSI field:
The last digits of the IMSI are typically masked or converted to zeros to prevent messaging fraud. If you have a legitimate need to query the full IMSI please contact us with you use case and required destination networks and we can check for availability.
Calculated META fields:
Note that reachable and validnumber fields are not data retrieved from the mobile networks via the HLR subsystem, but are calculated based on a set of conditions in the IMSI, Errorcode, and MSC responses to make an informed decision as to the current status of the number.
The "reachable" field:
The reachable field is a convenience flag computed by our API to indicate whether there is a good chance of a call or text reaching the subscriber's equipment at this moment. If a realtime HLR lookup returned a valid response with no HLR error code, then the number is considered to be "reachable". Due to availability of network coverage and other technical considerations, this is not a guarantee that any call or text will immediately reach the subscriber, if at all.If an error response is received, including temporary errors (such as "Absent Subscriber", which indicates the handset is offline) then reachable will show false. This is a realtime determination, and may change in a matter of hours or minutes; for example, a handset may be switched off, or out of coverage.
In the event of an HLR exception, or if the destination number is not in a realtime HLR region (for example, NANP), the API will return "undetermined" to indicate that the realtime reachability of this number cannot be calculated at present.
The "validnumber" field:
The validnumber field is a convenience flag computed on our system to indicate whether the MSISDN is a valid number assigned to an active subscriber (as opposed to an unassigned, or deactivated number). The validnumber flag will show true if a realtime HLR response returns either no error, or a temporary error which indicates the number is known to the operator, such as "Absent Subscriber".This field does not offer any opinion as to the reachability of a number, only that it appears to be a valid number and is likely to be assigned to an active subscriber of the mobile network operator.
In the event that an HLR exception occurs or the number is not in a realtime HLR region (such as NANP numbers), the API will return "undetermined" to indicate that the validity of the number cannot be calculated at present.
Undetermined Status
In the event that we cannot calculate or provide these metadata fields, the API will return "undetermined". This does not indicate the query has failed or that there is any technical problem. For example, NANP numbers will show "undetermined" due to the lookup method used, which simply does not support these feature.
North American Number Lookup Response fields:
msisdn | The number queried |
ocn | The carrier's OCN Code |
carrier | The carrier's name |
numbertype | The type of number (eg "MOBILE", "PCS", "WIRELESS") for mobile, ("LANDLINE", "CLEC", or "RBOC") for landline |
List of possible error codes
The following is a list of response codes that can be returned in the errorcode and errortext fields:
Code | Message | Description / Possible Cause |
0 | Lookup Complete | HLR returned valid SM routing data in response to SRI query |
1 | Unknown Subscriber | There is no directory number for the mobile subscriber (GSM 09.02) |
5 | Unidentified Subscriber | MAP response from MSC/VLR returned a negative response (GSM 03.07) |
6 | Absent Subscriber (SM) | Subscriber record is marked as unavailable as there was no paging response from the handset. May be switched off, in low coverage, or subject to roaming restrictions. |
7 | Unknown Equipment | Subscriber's mobile device has not been recognised (EIR) |
8 | Roaming Not Allowed | Subscriber is roaming on another network where roaming agreements may not be fully in place |
9 | Illegal Subscriber | Mobile station failed authentication |
11 | Teleservice Not Provisioned | The recipient mobile station has no SMS subscription (GSM 09.02) |
12 | Illegal Equipment | Mobile station was black-listed |
13 | Call Barred | Rejected due to barring of the mobile station (see GSM 09.02, description of the Barring supplementary service, GSM 02.04 and 03.11, and description of Operator Determined Barring, GSM 02.41 and 03.15). |
21 | Facility not Supported | SMS is not provisioned in the VPLMN (GSM 09.02). |
27 | Absent Subscriber | VLR has no IMSI record, or if the record is marked "Subscriber Data Not Confirmed by HLR" (GSM 03.07) |
31 | Subscriber Busy for MT SMS | Rejected because of congestion encountered at the remote MSC |
32 | SM Delivery Failure | SM Delivery Failure has occurred |
33 | Message Waiting List Full | Rejected because the mobile station is out of storage |
34 | Partner System Failure | The network partner encountered an error performing this operation |
35 | Data Missing or Unroutable | No routing exists to reach this prefix at the current time |
36 | Lookup Failure | Network or protocol failure, or invalid numbering plan prefix |
38 | Rejected | HLR subsystem rejected number - non-mobile or unsupported carrier |
Checking your account balance
To query the balance of your account via the API pass the following parameters:
user | Your account username |
pass | Your account password |
query | balance |
Example Request:
https://api.numberportabilitylookup.com/npl?user=bob&pass=123&query=balance
The response will give your remaining account balance as the number of lookups that can be performed before your account is depleted.
Example Response
HTTP/1.1 200 OK
45999564
Note: When performing a number lookup, the response will contain a "userbalance" parameter which provides this information without needing to run a separate query=balance API call. In many circumstances, this may be more efficient.
Multiple Simultaneous Connections
By default your account allows a maximum of 5 simultaneous HTTP connections to our API from the same user at the same time. Any additional connections will be rejected with ERR RATE_LIMIT_EXCEEDED.We recommend that if you have a high volume of traffic, you send two or more queries (up to ten) per HTTP call by separating MSISDN numbers by commas. This increases the efficiency of the traffic as you are not establishing a connection and negotiating an HTTPS handshake for every individual number, but spreading that overhead across multiple lookups. In the event that you have a high volume of traffic and five threads is not sufficient please contact us.
Coverage Check API
Our coverage check API provides information on networks that are currently within our reach (close to 100% globally), the type of connection that will be used for a query, and the response you can expect for each network in our coverage.
Coverage API: Country List
https://api.numberportabilitylookup.com/coverage/countries.json
Provides a list of countries which may be supported.
iso2 | International Standards Organization ISO-2 country code |
countryname | Country name |
fixed_networks | Number of fixed-line networks supported |
mobile_networks | Number of mobile networks supported |
sri_coverage | Number of mobile networks covered by SRI with live subscriber status |
live_coverage | Number of networks by live connections without subscriber status |
feed_coverage | Number of networks covered by carrier data feeds |
total_coverage | Total number of networks covered in this country |
network_list | API URL of the network list for this country |
Coverage API: Network List
https://api.numberportabilitylookup.com/coverage/countries/{country}/networks.json
Provides a list of supported networks in the specified country.
iso2 | international Standards Organization ISO-2 country code |
countryname | Country name |
lastupdate | When the coverage data was last updated (usually hourly) |
mcc | Mobile country code of the operator (SIM IMSI Prefix) |
mnc | Mobile network code of the operator (SIM IMSI Prefix) |
netname | Name of the operator |
nettype | Type of network operator (mobile/fixedline) |
coverage | Is the network covered by our service (true or false) |
connectiontype | How the lookup is performed ("sri", "portability", or "datafeed") |
subscriberstatus | Is live subscriber/handset status available (true or false) |
portstatus | Type of number port information: ("live" or "datafeed") |
For Further Assistance
For further assistance with the API, please [ Contact us ]
For an instant-setup account to try our API - [ click here ]
Usage of this API implies agreement with our terms and conditions for use [ View Terms]
|