 |
|
|
|
Number Portability Lookup HLR HTTP APIExample 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.2
Introduction to the API
Connectivity to the serviceConnectivity to the API is provided by via HTTP(s) GET or POST to the following URL:
https://api.numberportabilitylookup.com/nplYou can make an HTTP GET, or HTTP POST request; the latter is recommended if you are looking up a large quantity of numbers in a single request. There is a maximum of 100 numbers per request, and a maximum of one concurrent connection per account. Note that SS7 querying can take a while to process, so a large batch of numbers may take a while to return fully return.
Performing an HLR Lokup
In order to perform an HLR query on one or more mobile numbers, pass the following parameters:
Note: The CSV format is the default is no 'format' parameter is passed, and is included for legacy compatibility with older clients. It provides IMSI and MSC only. A much richer set of data about the number is available using the JSON or XML formats, so these are strongly recommended for new integrations.
Example Request: https://api.numberportabilitylookup.com/npl?user=bob&pass=123&msisdn=447788450450,447810701702&msc=1&format=json
Number Formatting
Example: UK 07788 450 450 -> 447788450450 Errors which could prevent your HLR lookup being run
Example Responses
<responsedata> <response> <countrycode>44</countrycode> <countryiso>GB</countryiso> <countryname>United Kingdom</countryname> <errorcode>0</errorcode> <errortext>OK</errogtext> <imsi>234158341040126</imsi> <localformat>07788 450450</localformat> <mcc>234</mcc> <mnc>15</mnc> <msc>44778</msc> <msisdn>447788450450</msisdn> <operatorname>Vodafone</operatorname> <originalmcc>234</originalmcc> <originalmnc>15</originalmnc> <originaloperatorname>Vodafone</originaloperatorname> <plmn>23415</plmn> <pogted>false</pogted> <reachable>true</reachable> <transactioncost>1.20</transactioncost> <validnumber>true</validnumber> </response> </responsedata> Example JSON Format Response
[
{
"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
QUERYOK 447788450450 23415,234158341040126,44778 ENDBATCH
Description of data fields contained in response
Notes on meta flags: The 'reachable' flag is a convenience flag computed on our system based on whether a full reachable IMSI was returned from the HLR subsystem - indicating that a call or text should be able to reach the subscriber equipment at this moment. If an error response is received (including temporary errors such as "Absent Subscriber" - which indicates the handset is off) then reachable will show 'false'. This is a realtime status, and does not indicate that the number might not be reachable in a few hours (maybe it's turned off overnight, or for a flight). In the event that an HLR exception occurs, or the destination number is not in a full HLR zone (such as NANP numbers), then "undetermined" will be returned to indicate that the realtime reachability status of this number could not be determined with certainty. The 'validnumber' flag 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 un-assigned, or de-activated number). The "validnumber" flag will show "true" if a full IMSI (>5 digits) is returned (indicating a full realtime HLR reply), or if the remote HLR indicates a temporary error condition that could only be indicated if that subscriber were one of its own - such as, Absent Subscriber (in which case "reachable" will indicate "false" to show that the number, while it appears to belong to a subscriber, is not currently reachable for SMS). In the event that an HLR exception occurs, a security IMSI-Prefix-Only route is used, or the number is not in a full HLR zone (such as NANP numbers), then "undetermined" will be returned to indicate that it was not possible to determine with certainty that this number is assigned to an active subscriber. Note that reachable and validnumber fields are not returned by the HLR subsystem, but calculated based on a set of conditions in the IMSI, Errorcode, and MSC responses we receive in order to make an informed decision as to the current status of the number. In the event that we cannot guarantee that status due to external factors, we will return "undetermined" for these fields. 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 OCN lookup method used in the US, which does not need to perform a realtime HLR query. Serving MSC (Mobile Switching Centre)
The MSC value is only returned if requested by passing parameter msc=1 in your request. Adding the serving MSC address prefix to your HLR request will incease the cost to 1.2 credits for that HLR query. Be aware that we will only return the prefix of the MSC (up to 5 digits) and not the full MSC address in order to reduce the possibility of clients engaging in messaging fraud, and this is not negotiable. North American Number Lookup Response fields:
List of possible error codesThe following is a list of response codes that can be returned in the errorcode and errortext fields:
Checking your account balance
Example Request:
http://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
Multiple Simultaneous Connections
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 making a socket connection and sending HTTP headers 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 your account manager.
For Further AssistanceFor 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] |
|
NumberPortabilityLookup.com™ & © 2021 SES IP Holdings Ltd - All Rights Reserved. Service operated by Wizard Island Software LLC. |