Number provisioning API

The Number Provisioning API allows you to assign UK geographic and non-geographic numbers to your own SIP endpoints. If you own a SIP router or PBX, such as asterisk, we can assign UK PSTN phone numbers from our own numbering ranges to your own PBX or reseller platform.

Our API uses 128-bit SSL encryption and allows resellers to search for available number ranges and assign numbers in real time via HTTP POST.

Please note that you would need your reseller username and password to run either script.


Process overview

Our API is divided into two processes. The relevant gateway API URL is listed next to the appropriate process.

1. Querying of available numbers
This returns a list of available numbers for you to choose from for use in step 2.
https://gw.aql.com/telecoms/checknumberapi.php

2. Assigning numbers
This stage assigns the numbers to your account and activates them. In response, you will receive the VOIP username and password for each of the numbers in the request.
https://gw.aql.com/telecoms/assignnumberapi.php

All the communications between client and gateway are carried out using the HTTP POST method.


Connection details

The gateways used for accessing the number provisioning API are as follows:


Querying available numbers

Request

This step requires the following HTTP POST parameters:

Variable Required Description
username Yes Reseller’s username
password Yes Reseller’s password
country Yes Country code of the number, UK is 44
areaCode Yes Area code of the number without the leading 0 (zero), e.g. 113 for Leeds instead of 0113
subCode Yes The remainder of the number – The subCode supports * as wildcard
skip Yes Acts to offset the responses by omitting the first x records
show Yes Limit (or increase) the result set returned to x
smsEnabled No Filter on whether numbers are SMS enabled. Accepts yes, no, ignore. Default: yes

Response

When a request is posted to our gateway, the response will be in the following format:

<RESPONSE_CODE>

<ADDITIONAL_INFO>

The possible values of <RESPONSE_CODE> are outlined in the following table:

Response Description
AQVOIP_FORMAT_ERROR One or more variables is not in the correct format (e.g. if areaCode contains alphabet)
AQVOIP_AUTH_ERROR Authentication error
AQVOIP_NO_NUMBER No number which matches the query is available
AQVOIP_OK Request is successful
AQVOIP_TEMP_ERROR Yes
skip Temporary error. Please try again in a few moments. We are working on resolution

Example:

To search for 0113 numbers beginning with 312012 you would use the following variables:
country = 44,
areaCode = 113 and
subCode = 312012*

The gateway would then return the following (only the first four numbers are shown here for clarity):

AQVOIP_OK
44-113-3120120_44-113-3120121_44-113-3120122_44-113-3120123_ …

Depending on the query, the second line of response might contain up to 100 different numbers.


Provisioning numbers

Request

This step requires the following HTTP POST parameters:

Variable Required Description
username Yes Reseller’s username
password Yes Reseller’s password
phoneNumbers Yes A list of the phone number(s) of all the numbers to be ac􀀭vated separated by underscores
firstNames Yes A list of all the first name(s) of the reseller’s customer separated by underscores
lastNames Yes A list containing all the last name(s) of the reseller’s customer separated by underscores
emails Yes A list containing all the email address(es) of the reseller’s customer separated by underscores
type Yes Pass “type” as “sip” to provision as SIP, otherwise will be provisioned as IAX

Example of how list variables should look like:

PhoneNumbers list should be passed in the format of:
44-113-3120120_44-113-3120121_44-113-3120122_44-113-3120123_ …

firstNames, lastNames and emails should be passed in the format of:
Robert_James_John_…

Important:

It is important to note that the size (i.e. number of elements) of all of these lists have to be exactly the same. If that is not the case, the response AQVOIP_FORMAT_ERROR will be issued.

The values for the firstNames, lastNames and emails parameters may contain an empty string. If these fields are left blank, this may affect some aql VoIP functionality. An example would be sending a sound file containing a voicemail message to a customer email address if they have a voicemail.

Response

The response from our gateway will be of the following format:

<RESPONSE_CODE> <REAL NUMBER>_<VOIP_NUMBER>_<PASSWORD>
<REAL NUMBER>_<VOIP_NUMBER>_<PASSWORD>

<REAL NUMBER>_<VOIP_NUMBER>_<PASSWORD>

The possible values of <RESPONSE_CODE> are outlined in the following table:

Response Description
AQVOIP_FORMAT_ERROR One or more variables is not in the correct format (e.g. if areaCode contains alphabet)
AQVOIP_AUTH_ERROR Authentication error
AQVOIP_SIMUL_ERROR 1. One or more number in the phoneNumbers variable is not available to be assigned. Please check using our check available number API. 2. Or other reseller/customer is trying to assign the same number for themselves. Restarting the process or choosing a different set of numbers would usually solve this problem.
AQVOIP_GEN_ERROR General error that arises during number assignment. Please contact our support team on 01133 203040 if the problem persists.
AQVOIP_OK Request is successful.
AQVOIP_TEMP_ERROR Temporary error. Please try again in a few moments. We are working on resolution.

Important:

The order of voipnumber and password will correspond to the order of phoneNumbers, firstNames, lastNames and emails sent to our gateway in step 2.

An example response from this gateway would be:

AQVOIP_OK
44-113-3120120_612345_98765
44-113-3120121_654321_45848

Notes:

  • For the number provisioning API, we maintain the policy of “assign all” or none. This helps avoid any inconsistency or anomalies – if an error occurs in any part of the process then none of the numbers will be assigned even though the error might occur halfway through the provisioning process
  • The monthly price for activating a geographic number will be charged to your account and you will be invoiced monthly
  • It is an advisable practice to check and recheck if numbers are still available using query available number API (see above) before assigning them. However, this is not compulsory
  • All lines in the API are terminated by \n and not \r\n

Number availability

aql has over nine million UK geographic numbers ready to be assigned within seconds. Visit www.aql.com for more information.