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:

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) economy 1 = 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:

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

Account Balance Query

To query the balance of your account via the API pass the following parameters:

user Your account username pass Your account password query balance

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]