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