My Account  |   Register  |   Pricing  |   Asterisk Integration  |   API Documentation   |   Sample Code  |   Network List  |   Status  |   About Us  |   Contact

Sample Code & Asterisk DialPlan Integration

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

Recent API version history:

V2.4 - Addition of IMSI and MSC information to lookup response
     - Added 'apiver' (version) parameter. If omitted, response output conforms to V2.3
V2.3 - Added standard GSM error codes to give more information on lookup failures
V2.2 - US and Canada now use standard MCC/MNC tuples in place of old texual network names

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 one of the following URLs:

    http://api.comcetera.com/npl
    https://secure.comcetera.com/npl (Recommended)
    

Making a request

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

Request Format

    Your HTTP request should include the following parameters:

    userYour account username
    passYour account password
    apiverThe latest API version known to your software. If left blank it will default to legacy version 2.3 for backward compatibility with old software.
    msisdnThe number(s)* to look up (seperated by commas)

    * All numbers should be specified in the standard international format (without the leading '+' symbol).

    Example: UK (Country 44) number 07788 450 450 would be specified as 447788450450
    Example: USA (Country 1) number 704-451-8989 would be specified as 17044518989

    If you need help for a specific country, please [ Contact us ].

    Example Request:

    http://api.comcetera.com/npl?user=bob&pass=123&apiver=2.4&msisdn=447788450450,447810701702

Response from our service

    Query Validity

    The first line of the response from our system indicates whether your query was accepted.

    Possible responses are:

    QUERYOK
    FAIL Invalid password
    FAIL Insufficient credit
    FAIL No numbers specified
    FAIL Request too long
    ERR ACCOUNT LOCKED - Please arrange payment *
    
    * This error is only received by customers with a post-paid invoice arrangement with us, and whose account is more than 6 months overdue.

    Number Lookup Responses

    If your query was accepted (you received a QUERYOK), each number in your query list will be shown on (one per line) followed by a space, followed by the lookup response for that MSISDN.

    The end of the batch is marked by "ENDBATCH" on a line by itself, and the HTTP connection will automatically close.

    Example Response (Latest API Version: 2.4)

    HTTP/1.1 200 OK
    
    QUERYOK
    447788450450 23415,447785014185,234158341040126
    447810701702 23415,447785014185,234159002945116
    447973100100 ERR1
    ENDBATCH
    
    Example Response (Legacy API Version 2.3 or older) - used if no "apiver" parameter is passed in your query
    HTTP/1.1 200 OK
    
    QUERYOK
    447788450450 23415
    447810701702 23415
    447973100100 ERR1
    ENDBATCH
    

    Response Codes

    Next to each number in your query list, you will see a response code.

    If your query was successful, and you are using the latest version of the API (by passing apiver=2.4 in your query string), the response code will consist of three values separated by commas:

      1. The MCC/MNC network code of the network to which the number belongs
      2. The current serving MSC for the mobile subscriber
      3. The mobile subscriber's IMSI (if supported)

    Note: MNC and IMSI support was added to the API in version 2.4. If you do not pass apiver=2.4 (or higher) in your query string you will receive only the MCC/MNC network code without any additional information.

    If your query fails, this is indicated (as shown in the example above) by the string "ERR" followed by a GSM 03.47 error code indicating the reason for the failure. See the list below for more information.

    GSM 03.37 Error Codes

    The following list is the subset of the GSM 03.47 error codes which are relevant to this service:

    ERR1   Unknown subscriber         - There is no directory entry for the mobile subscriber
    ERR29  Absent subscriber          - IMSI record marked as detached, or subject to roaming restrictions
    ERR21  Facility not supported     - No provision for SMS in the VPLMN
    ERR11  Teleserice not provisioned - Recipient has no SMS subscription
    ERR13  Call barred                - MS is barred (Supplementaty 02.04/03.11 or Operator 02.41/03.15)
    ERR36  System Failure             - Message timed out or failed due to network or protocol failure
    

For Further Assistance

    For further assistance with the API, please [ Contact us ]

    For a free instant-setup trial account with 5 free credits to try our API - [ click here ]

Usage of this API implies agreement with our terms and conditions for use [ View Terms]

 
NumberPortabilityLookup.com is a brand of Comcetera™ Ltd, Suite 324, Hollybank House, Poole BH16 6AQ. Registered in England, Company 6058188.