Account  |   Register  |   Pricing  |   Asterisk  |   HTTP API   |   Code  |   Batch Client   |   Coverage  |   Status  |   About  |   Contact

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.3

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

    Connectivity to the API is provided by via HTTP(s) GET or POST to the following URL:

    https://api.numberportabilitylookup.com/npl
    
    You 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 Lookup

    In order to perform an HLR query on one or more mobile numbers, pass the following parameters:

    userYour account username
    passYour account password
    msisdnThe number(s) to look up in E.164 format. Separate multiple numbers with commas
    formatUse 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.
    mscPass 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 being run

    If there is a problem that prevents our system from running your HLR lookup you'll receive one of these error strings:

      FAIL Invalid passwordThe username or password you supplied were not correct.
      FAIL Insufficient creditYour account balance is too low. please add funds.
      No numbers specifiedYou did not include an msisdn parameter in your query.
      Request too longMore than ten msisdn numbers were included in a single query
      ERR RATE_LIMIT_EXCEEDEDYou've made more than the allowed number of concurrent connections to the server

Example Responses

    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

      The fields in the CSV response are: msisdn plmn,imsi,msc:

      QUERYOK
      447788450450 23415,234158341040126,44778
      ENDBATCH
      
      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:

    countrycodecountry code of number's home country
    countryisoISO 3166 country code of number's home country
    countrynameName of number's home country
    errorcodean error number if any error, otherwise 0
    errortexta description of the error code (otherwise "OK")
    imsithe international mobile subscriber id of the subscriber **
    landlinetrue if the number is a landline (fixed) number
    lrnlocation routing number for PSTN calls (NANP)
    localformatthe number formatted as it would be written in its home country
    mobiletrue if the number is a mobile number
    mccthe mobile country code of the home network
    mncthe mobile network code of the home network
    msisdnthe mobile number to which this query pertains
    numbertypethe type of number (MOBILE,LANDLINE,VOIP,TOLLFREE)
    ocnoperating carrier number (NANP)
    operatornamethe name of the home network operator
    originalmccthe mcc of the original operator (if ported)
    originalmncthe mnc of the original operator (if ported)
    originalcarrierthe name of the original carrier (if ported)
    originaloperatornamethe name of the original operator (if ported)
    plmnpublic land mobile network code of home network (mcc+mnc)
    portedwhether the number has been ported (true/false)
    reachable(meta) whether the number is in coverage and reachable (true/false/undetermined)
    spidService Profile ID
    timezonetime zone where the number is registered
    transactioncostcost of this lookup in credits (eg 1.00)
    validnumber(meta) whether the number is a valid subscriber (true/false/undetermined)

**Note on 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.

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 unassigned, or deactivated 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 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 increase 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:

  • 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, 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:

      CodeMessageDescription / Possible Cause
      0Lookup CompleteHLR returned valid SM routing data in response to SRI query
      1Unknown Subscriber there is no directory number for the mobile subscriber (GSM 09.02)
      5Unidentified Subscriber MAP response from MSC/VLR returned a negative response (GSM 03.07)
      6Absent 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.
      7Unknown Equipment Subscriber's mobile device has not been recognised (EIR)
      8Roaming Not Allowed Subscriber is roaming on another network where roaming agreements may not be fully in place
      9Illegal Subscriber mobile station failed authentication
      11Teleservice Not Provisioned the recipient mobile station has no SMS subscription (GSM 09.02)
      12Illegal Equipment mobile station was black-listed
      13Call 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).
      21Facility not SupportedSMS is not provisioned in the VPLMN (GSM 09.02).
      27Absent Subscriber VLR has no IMSI record, or if the record is marked "Subscriber Data Not Confirmed by HLR" (GSM 03.07)
      31Subscriber Busy for MT SMS rejected because of congestion encountered at the remote MSC
      32SM Delivery Failure SM Delivery Failure has occurred
      33Message Waiting List Full rejected because the mobile station is out of storage
      34Partner System Failure the network partner encountered an error performing this operation
      35Data Missing or Unroutable no routing exists to reach this prefix at the current time
      36Lookup Failure network or protocol failure, or invalid numbering plan prefix
      38Rejected 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:

    userYour account username
    passYour account password
    querybalance

    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

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

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.

    There is no authentication required for access to the Coverage Check API.

    [REST] Coverage API Endpoint:

      https://api.numberportabilitylookup.com/coverage/

    Rate Limiting:

      There is currently no rate limit on the coverage API.

    [GET] Country List

      To obtain a list of covered countries send a GET request to the countries method:
      https://api.numberportabilitylookup.com/coverage/countries.json

      Example Request:

      [GET] https://api.numberportabilitylookup.com/coverage/countries.json

    [GET] Network List

      To obtain a list of covered networks in a country, send a GET request to the networks method for that country:
      https://api.numberportabilitylookup.com/coverage/countries/{country}/networks.json

      Example Request (United States of America):

      [GET] https://api.numberportabilitylookup.com/coverage/countries/US/networks.json

    Description of data fields returned by the Coverage API:

      Country List Fields:

      • 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

      Network List Fields:

      • 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|false)
      • connectiontype - how the NPL query is performed (sri|portability|datafeed)
      • subscriberstatus - is live subscriber/handset status available (true|false)
      • portstatus - type of number port information: (live|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]



 
NumberPortabilityLookup.com™ & © 2024 SES IP Holdings Ltd - All Rights Reserved. Service operated by Wizard Island Software LLC.