My Account  |   Register  |   Pricing  |   Asterisk Integration  |   API Details   |   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.5

Recent API version history:


V2.5 - Addition of 'economy' parameter to allow per-query control of cached vs live query
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)
    economy1 = attempt economy query**, 0 = always perform live query. If this parameter is omitted, the economy mode setting configured in your online account will be used.

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

    ** Economy query: If the number has been queried by you, or any of our other clients in the last 24 hours, we'll return the result from our cache database for 0.2 of a credit rather than performing a live lookup over the network. You can set this from your online account, or, using the 'economy' API parameter override this setting per query.

    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 - Global Lookups

    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.

    Response Codes - North American Numbering Plan

    If you query a number in country code '1' you will see additional fields in the response.

    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 OCN Code of the network to which the number belongs
      2. The name of the provider
      3. MOBILE or LANDLINE

    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:

    ERR1Unknown subscriberThere is no directory entry for the mobile subscriber
    ERR29Absent subscriberIMSI record marked as detached, or subject to roaming restrictions
    ERR21Facility not supportedNo provision for SMS in the VPLMN
    ERR11Teleserice not provisionedRecipient has no SMS subscription
    ERR13Call barredMS is barred (Supplementaty 02.04/03.11 or Operator 02.41/03.15)
    ERR36System FailureMessage timed out or failed due to network or protocol failure

Account Balance Query

    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.comcetera.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. Note that if you have ever used our economy mode, this balance may not be an integer.

    Example Response

    HTTP/1.1 200 OK
    
    45999564
    

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]

 
© 2011 Comcetera Ltd. NumberPortabilityLookup.com is a product of Comcetera™ Ltd
Comcetera Ltd is Registered in England, Company 6058188 at Unit 13 Freeland Business Park, Poole BH16 6FH.