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:

user Your account username pass Your account password apiver The latest API version known to your software. If left blank it will default to legacy version 2.3 for backward compatibility with old software. msisdn The 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]