Other Services
Click here to view aql's range of voice fax and Business Voice over IP telephony solutions.
Click Here...
999 API Access
Contents
- 2.1 Activate Customer
- 2.2 Cease Customer
- 2.3 Modify Customer
- 2.4 Export Number
- 2.5 Import Number
- 2.6 Get Last ID By Number
- 2.7 Get Record By ID
1.1 Introduction
This API is designed to allow holders of aql® numbers to update their subscriber details with BT’s 999 system. This will provide an easy method for the update of BT’s 999 record details for our customers.
1.2 Interface Protocol
The protocol presented is HTTPS. All the API methods will be executed by a standard POST request of the HTTPS protocol.
The gateway URL for all calls is located at https://gw.aql.com/telecoms/999.api.php
1.3 Interface Methods
The interface methods will be as follows:
- Activate Customer
- Cease Customer
- Modify Customer
- Export Number
- Import Number
- Get Record IDs By Number
- Get Record By ID
1.4 Return Codes
Return codes used will be the standard meanings for 200 OK, 404 Unauthorised and 500 INTERNAL ERROR.(see error codes)
2.1 Activate Customer
Request
Description: Used to activate a number with associated customer details at BT’s TDM system.
| Parameter | Value | Required/ Optional | Max Length | Description |
|---|---|---|---|---|
| command | activate | Required | - | Activate Command |
| username | Alphanumeric | Required | - | aql username. |
| password | Alphanumeric | Required | - | aql Password. |
| number | Numeric | Required | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| postcode | Alphanumeric | Required | 8 | Customer’s postcode. This must be sent in the format of Out-code space In-code i.e.: LS11 5DF, S9 5AD, S60 3ML. |
| effective_date | Numeric | Required | - | Date on which the command associated with the listing is to be executed. Format used must be YYYY-MM-DD (where Y = Year, M = Month & D = Day) |
| surname | Alphanumeric | Required | 50 | Name of the customer. |
| title | Alphanumeric | Optional | 20 | Title of the customer. |
| forename | Alphanumeric | Optional | 20 | Forename of the customer. |
| honours | Alphanumeric | Optional | 30 | Honours of the customer. |
| business_suffix | Alphanumeric | Optional | 50 | Business suffix |
| line_type | Alphanumeric | Optional | 30 | ** Line type. See below |
| premises | Alphanumeric | Optional | 60 | Identifies premises on a thoroughfare i.e. house name and/or number. Example 24 and/or Bleak House |
| thoroughfare | Alphanumeric | Optional | 55 | The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street. |
| locality | Alphanumeric | Optional | 30 | Village or an area within a town and Town if possible. |
| notify-email | Alphanumeric | optional | - | The email address to notify when a staus change occurs. Optional, but will reduce functionality if ommitted. |
| return-mode | Blank | optional | - | return-mode parameter |
| return-format | Blank | optional | - | return-mode parameter |
** This is for DDI/VoIP type number ranges or it basically will add a flag to show that the record which is being sent may not reflect the actual location of the caller. Options for the population of this field are EXT, DDI, FNET, or VOIP any of these possible mnemonic’s will flag to the Operator as well as an Emergency Authority who has the EISEC service. (This allows the Emergency Authority to see the name and address details we have for a customer at the time of a 999 call)
Output Parameters
Return format of FAILED command :
<status_code>: <text_description>
Return format of SUCCESS command :
<status_code>: <text_description>
id: <id>
2.2 Cease Customer
Request
Method: POST
Description: Used to remove the requested number at BT’s TDM system.
| Parameter | Value | Required/ Optional | Max Length | Description |
|---|---|---|---|---|
| command | cease | Required | - | Cease Customer Command |
| username | Alphanumeric | Required | - | aql username. |
| password | Alphanumeric | Required | - | aql password. |
| number | Numeric | Required | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| effective_date | Numeric | Required | - | Date on which the command associated with the listing is to be executed. Format used must be YYYY-MM-DD (where Y = Year, M = Month & D = Day) |
| notify-email | Alphanumeric | optional | - | The email address to notify when a staus change occurs. Optional, but will reduce functionality if ommitted. |
| return-mode | Blank | optional | - | return-mode parameter |
| return-format | Blank | optional | - | return-mode parameter |
Output Parameters
Return format of FAILED command :
<status_code>: <text_description>
Return format of SUCCESS command :
<status_code>: <text_description>
id: <id>
2.3 Modify Customer
Request
Method: POST
Description: Used to modify the requested number’s customer details at BT’s TDM system.
| Parameter | Value | Required/ Optional | Max Length | Description |
|---|---|---|---|---|
| command | modify | Required | - | Modify Customer Command |
| username | Alphanumeric | Required | - | aql username. |
| password | Alphanumeric | Required | - | aql Password. |
| number | Numeric | Required | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| postcode | Alphanumeric | Required | 8 | Customer’s postcode. This must be sent in the format of Out-code space In-code i.e.: LS11 5DF, S9 5AD, S60 3ML. |
| effective_date | Numeric | Required | - | Date on which the command associated with the listing is to be executed. Format used must be YYYY-MM-DD (where Y = Year, M = Month & D = Day) |
| surname | Alphanumeric | Required | 50 | Name of the customer. |
| title | Alphanumeric | Optional | 20 | Title of the customer. |
| forename | Alphanumeric | Optional | 20 | Forename of the customer. |
| honours | Alphanumeric | Optional | 30 | Honours of the customer. |
| business_suffix | Alphanumeric | Optional | 50 | Business suffix |
| line_type | Alphanumeric | Optional | 30 | ** Line type. See below |
| premises | Alphanumeric | Optional | 60 | Identifies premises on a thoroughfare i.e. house name and/or number. Example 24 and/or Bleak House |
| thoroughfare | Alphanumeric | Optional | 55 | The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street. |
| locality | Alphanumeric | Optional | 30 | Village or an area within a town and Town if possible. |
| notify-email | Alphanumeric | optional | - | The email address to notify when a staus change occurs. Optional, but will reduce functionality if ommitted. |
| return-mode | Blank | optional | - | return-mode parameter |
| return-format | Blank | optional | - | return-mode parameter |
** This is for DDI/VoIP type number ranges or it basically will add a flag to show that the record which is being sent may not reflect the actual location of the caller. Options for the population of this field are EXT, DDI, FNET, or VOIP any of these possible mnemonic’s will flag to the Operator as well as an Emergency Authority who has the EISEC service. (This allows the Emergency Authority to see the name and address details we have for a customer at the time of a 999 call)
Output Parameters
Return format of FAILED command :
<status_code>: <text_description>
Return format of SUCCESS command :
<status_code>: <text_description>
id: <id>
2.4 Export Number
Request
Description: Used initiate an export to another carrier at BT’s TDM system.
| Parameter | Value | Required/ Optional | Max Length | Description |
|---|---|---|---|---|
| command | export | Required | - | Export Customer Command |
| username | Alphanumeric | Required | - | aql username. |
| password | Alphanumeric | Required | - | aql Password. |
| number | Numeric | Required | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| postcode | Alphanumeric | Required | 8 | Customer’s postcode. This must be sent in the format of Out-code space In-code i.e.: LS11 5DF, S9 5AD, S60 3ML. |
| effective_date | Numeric | Required | - | Date on which the command associated with the listing is to be executed. Format used must be YYYY-MM-DD (where Y = Year, M = Month & D = Day) |
| cp_identifier | Numeric | Required | - | CUPID of importing CP. |
| return-mode | Blank | optional | - | return-mode parameter |
| return-format | Blank | optional | - | return-mode parameter |
Output Parameters
Return format of FAILED command :
<status_code>: <text_description>
Return format of SUCCESS command :
<status_code>: <text_description>
id: <id>
2.5 Import Number
Request
Description: Used to confirm the import of a number from other carrier at BT’s TDM system.
| Parameter | Value | Required/ Optional | Max Length | Description |
|---|---|---|---|---|
| command | import | Required | - | Import Customer Command |
| username | Alphanumeric | Required | - | aql username. |
| password | Alphanumeric | Required | - | aql Password. |
| number | Numeric | Required | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| cp_identifier | Numeric | Required | - | CUPID of exporting CP. |
| postcode | Alphanumeric | Required | 8 | Customer’s postcode. This must be sent in the format of Out-code space In-code i.e.: LS11 5DF, S9 5AD, S60 3ML. |
| effective_date | Numeric | Required | - | Date on which the command associated with the listing is to be executed. Format used must be YYYY-MM-DD (where Y = Year, M = Month & D = Day) |
| surname | Alphanumeric | Required | 50 | Name of the customer. |
| title | Alphanumeric | Optional | 20 | Title of the customer. |
| forename | Alphanumeric | Optional | 20 | Forename of the customer. |
| honours | Alphanumeric | Optional | 30 | Honours of the customer. |
| business_suffix | Alphanumeric | Optional | 50 | Business suffix |
| line_type | Alphanumeric | Optional | 30 | ** Line type. See below |
| premises | Alphanumeric | Optional | 60 | Identifies premises on a thoroughfare i.e. house name and/or number. Example 24 and/or Bleak House |
| thoroughfare | Alphanumeric | Optional | 55 | The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street. |
| locality | Alphanumeric | Optional | 30 | Village or an area within a town and Town if possible. |
| return-mode | Blank | optional | - | return-mode parameter |
| return-format | Blank | optional | - | return-mode parameter |
** This is for DDI/VoIP type number ranges or it basically will add a flag to show that the record which is being sent may not reflect the actual location of the caller. Options for the population of this field are EXT, DDI, FNET, or VOIP any of these possible mnemonic’s will flag to the Operator as well as an Emergency Authority who has the EISEC service. (This allows the Emergency Authority to see the name and address details we have for a customer at the time of a 999 call)
Output Parameters
Return format of FAILED command :
<status_code>: <text_description>
Return format of SUCCESS command :
<status_code>: <text_description>
id: <id>
2.6 Get Last ID By Number
Request
Description: Returns the last ID associated with the requested phone number.
| Parameter | Value | Required/ Optional | Max Length | Description |
|---|---|---|---|---|
| command | getlastidbynumber | Required | - | Get the last ID associated with a number |
| username | Alphanumeric | Required | - | aql username. |
| password | Alphanumeric | Required | - | aql Password. |
| number | Numeric | Required | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| return-mode | Blank | optional | - | return-mode parameter |
| return-format | Blank | optional | - | return-mode parameter |
Output Parameters
Return format of FAILED command :
<status_code>: <text_description>
Return format of SUCCESS command :
<status_code>: <text_description>
id: <id>
2.7 Get Record By ID
Request
Description: Returns all attributes of requested record.
| Parameter | Value | Required/ Optional | Max Length | Description |
|---|---|---|---|---|
| command | getrecordbyid | Required | - | Retrieve all records for an ID |
| username | Alphanumeric | Required | - | aql username. |
| password | Alphanumeric | Required | - | aql Password. |
| number | Numeric | Required | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| id | Numeric | Required | - | Record ID number |
| return-mode | Blank | optional | - | return-mode parameter |
| return-format | Blank | optional | - | return-mode parameter |
Output Parameters
| Record status: | |
|---|---|
| READY: | Data captured and ready to send * |
| PENDING: | Data submitted |
| COMPLETE: | Request completed |
| FAILED: | Request failed |
* All 999 update requests are collated and sent in batches periodically.
id: <id>
created: <created> command: <command>
record_status: <record_status>
postcode: <postcode>
effective_date: <effective_date>
surname: <surname>
title: <title>
forename: <forename>
honours: <honours>
business_suffix: <business_suffix>
line_type: <line_type>
thoroughfare: <thoroughfare>
locality: <locality>
cp_identifier: <cp_identifier>
ret_code: <ret_code>
err_msg: <err_msg>
3.1 Responses
Return Codes
| Return Code | Msg Text | Actions to be taken |
|---|---|---|
| 13 | Telephone Number Missing. | DATA DELIVERY TEAM TO BUILD RANGE AND RETRY IF APPLICABLE, OR CP TO CORRECT ENTRY |
| 14 | Telephone Number Invalid. | DATA DELIVERY TEAM TO BUILD RANGE AND CP TO RESUBMIT |
| 18 | OLO does not own Entry. | CP TO INVESTIGATE - IF DISPUTED CONTACT DATA DELIVERY TEAM |
| 19 | Invalid OLO. | DATA DELIVERY TEAM TO CHECK VALIDITY OF CP AND CP TO RESEND IF APPLICABLE. |
| 28 | Renumber in Invalid Range. | DATA DELIVERY TEAM TO BUILD RANGE IF APPLICABLE AND REQUEST CP TO RESUBMIT - OR CP TO CORRECT ENTRY |
| 33 | Cancellation Successful. | NO ACTION |
| 34 | Cancellation Invalid. | CP TO SUBMIT CORRECTION AS AMENDMENT |
| 35 | Cancellation Unsuccessful. | CP TO SUBMIT CORRECTION AS AMENDMENT |
| 37 | New Record Successful. | NO ACTION |
| 38 | Cease Record Successful. | NO ACTION |
| 39 | NAA Record Successful. | NO ACTION |
| 40 | Renumber Successful. | NO ACTION |
| 43 | Export/Import OLO Mismatch. | CP TO CORRECT AND RESUBMIT. THIS APPLIES TO EITHER THE GAINING OR LOSING CP AS TDM IS UNABLE TO DISTINGUISH WHICH IS CORRECT / INCORRECT |
| 45 | Import Record is Missing. | GAINING CP TO RE-SUBMIT |
| 46 | Import is 28 days overdue. | LAST WARNING BEFORE DELETION - CP TO RESUBMIT |
| 47 | Export Record is Missing. | LOSING CP TO RESUBMIT |
| 48 | Export is 28 days Overdue. | LAST WARNING BEFORE DELETION – CP TO RESUBMIT |
| 49 | Export removed, no Import. | CP TO RESUBMIT UNLESS IMPORT FROM BT. IN WHICH CASE ANY FUTURE CHANGES SHOULD BE DEALT WITH AS AN AMEND |
| 50 | Import removed, no Export. | CP TO RESUBMIT UNLESS IMPORT FROM BT. IN WHICH CASE ANY FUTURE CHANGES SHOULD BE DEALT WITH AS AN AMEND |
| 53 | Export/Import dates differ. | WARNING ONLY - WILL BE PROCESSED ON LATEST DATE |
| 55 | Export Record Successful. | NO ACTION |
| 56 | Import Record Successful. | NO ACTION |
| 60 | Postcode not found. | DATA DELIVERY TEAM TO CHECK POSTCODE WITH ROYALMAIL AND RETRY IF VALID. IF POSTCODE IS INVALID LO WILL BE NOTIFIED BY DATA DELIVERY TEAM, CP TO THEN CORRECT AND THEN RESUBMIT |
| 61 | Postcode is acceptable. | NO ACTION |
| 73 | Record Received. | NO ACTION |
| 75 | More Recent Record exists. | CP TO INVESTIGATE |
| 100 | Blank record. | BLANK RECORD, CP TO CORRECT AND RESUBMIT |
| 101 | Invalid record type. | RECORD TYPE MISSING, CP TO CORRECT AND RESUBMIT |
| 102 | Feed Type is missing. | COMMAND VALUE NOT PRESENT IN RECORD, CP TO CORRECT AND RESUBMIT |
| 103 | Feed Type is incorrect. | INVALID COMMAND VALUE IN RECORD, CP TO CORRECT AND RESUBMIT |
| 104 | OLO ID is missing. | CP ID NOT PRESENT IN RECORD, CP TO CORRECT AND RESUBMIT |
| 105 | Invalid OLO ID. | INVALID CHARACTER IN CP ID FIELD, CP TO CORRECT AND RESUBMIT |
| 106 | OLO ID in record not owned by OLO in header. | CP ID IN RECORD NOT OWNED BY CP IN HEADER, CP TO CORRECT AND RESUBMIT |
| 107 | Reference ID is missing. | CP TRANSACTION ID NOT PRESENT IN RECORD, CP TO CORRECT AND RESUBMIT |
| 108 | Reference ID incorrect. | INVALID CHARACTERS IN CP TRANSACTION ID, CP TO CORRECT AND RESUBMIT |
| 109 | System Routing Flags is missing. | SYSTEM ROUTING FLAG NOT PRESENT IN RECORD, CP TO CORRECT AND RESUBMIT |
| 110 | System Routing Flags incorrect. | INVALID CHARACTERS IN SYSTEM ROUTING FLAGS, CP TO CORRECT AND RESUBMIT |
| 111 | 999 routing Flag set to ‘N’. | FLAG 1 OR 2 IN SYSTEM ROUTING FLAGS FIELD MUST BE SET TO 'Y', CP TO CORRECT AND RESUBMIT |
| 112 | NI only record found in file. | NO NI-ONLY RECORDS ARE ACCEPTED VIA TELESTO, CP TO CORRECT AND RESUBMIT |
| 113 | Invalid Effective Date. | DATE INCORRECT, CP TO CORRECT AND RESUBMIT |
| 114 | Title is incorrect. | INVALID VALUE IN TITLE FIELD, CP TO CORRECT AND RESUBMIT |
| 115 | Initials / Forename is missing. | INITIALS / FORENAME NOT PRESENT IN RECORD, CP TO CORRECT AND RESUBMIT |
| 116 | Initials / Forename is incorrect. | INVALID VALUE IN INITIALS / FORENAME FIELD, CP TO CORRECT AND RESUBMIT |
| 117 | Name is missing. | NAME VALUE NOT PRESENT IN RECORD, CP TO CORRECT AND RESUBMIT |
| 118 | Name is incorrect. | INVALID CHARACTERS IN NAME FIELD, CP TO CORRECT AND RESUBMIT |
| 119 | Honours is incorrect. | INVALID VALUE IN HONOURS FIELD, CP TO CORRECT AND RESUBMIT |
| 120 | Business Suffix is incorrect. | INVALID VALUE IN BUSINESS SUFFIX FIELD, CP TO CORRECT AND RESUBMIT |
| 121 | Premises is incorrect. | INVALID VALUE IN PREMISES FIELD, CP TO CORRECT AND RESUBMIT |
| 122 | Thoroughfare is incorrect. | INVALID VALUE IN THOROUGHFARE FIELD, CP TO CORRECT AND RESUBMIT |
| 123 | Locality is incorrect. | INVALID VALUE IN LOCALITY FIELD, CP TO CORRECT AND RESUBMIT |
| 124 | Post Code is missing. | POST CODE NOT PRESENT IN RECORD, CP TO CORRECT AND RESUBMIT |
| 125 | Post Code is incorrect. | INVALID CHARACTERS IN POST CODE FIELD, CP TO CORRECT AND RESUBMIT |
| 126 | Telephone number not present in record. | TELNO VALUE NOT PRESENT IN RECORD, CP TO CORRECT AND RESUBMIT |
| 127 | Telephone Number Invalid. | INVALID CHARACTERS IN TELNO FIELD, CP TO CORRECT AND RESUBMIT |
| 128 | New Telephone number is missing. | NEW TELEPHONE NUMBER IS NOT PRESENT IN THE RECORD, CP TO CORRECT AND RESUBMIT |
| 129 | New Telephone number is incorrect. | NEW TELEPHONE NUMBER CONTAINS INVALID CHARACTERS, CP TO CORRECT AND RESUBMIT |
| 130 | New OLO ID is missing. | NEW CP ID VALUE NOT PRESENT IN RECORD, CP TO CORRECT AND RESUBMIT |
| 131 | New OLO ID is incorrect. | INVALID CHARACTERS IN SECOND CP FIELD, CP TO CORRECT AND RESUBMIT |
| 132 | Unknown Error. | CP TO CONTACT DATA DELIVERY TEAM |
Status Codes
| 200 | ok |
| 400 | bad request |
| 401 | authentication error |
| 500 | internal system error |
| 600 | invalid command |
| 67001 | number not valid or provided |
| 67013 | Number not on account |
| 67008 | Previous command stil pending |
| 67009 | Number already active. Cannot activate again |
| 67010 | Number must first be activated using the activate command |
| 67004 | surname not provided |
| 67002 | postcode not provided |
| 67003 | effective_date not provided |
| 67005 | line_type not provided |
| 67006 | cp_identifier not provided |
| 67011 | Number cannot be ceased because it is not already active |
| 67007 | id not provided |
| 67012 | Invalid id for that number. |