999 emergency service access API
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.
It is essential that all partners provide accurate and complete customer data. Failure to provide full and accurate information will delay the emergency services response to emergency situations.
Interface
Interface protocols
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
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
Return codes
Return codes used will be the standard meanings for 200 OK, 404 Unauthorised and 500 INTERNAL ERROR.
Activate customer
Request
Description:
Used to activate a number with associated customer details at BT’s TDM system.
| Parameter | Type | Required | Length | Description |
|---|---|---|---|---|
| command | Alphanumeric | Yes | Value must be “activate” | |
| username | Alphanumeric | Yes | aql username | |
| password | Alphanumeric | Yes | aql password | |
| number | Numeric | Yes | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| postcode | Alphanumeric | Yes | 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 | Alphanumeric | Yes | 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 | Yes | 50 | Name of the customer (if residential) or business Name |
| title | Alphanumeric | No | 20 | Title of the customer |
| forename | Alphanumeric | No | 20 | Forename of the customer |
| honours | Alphanumeric | No | 30 | Honours of the customer |
| business_suffix | Alphanumeric | No | 50 | Business suffix |
| line_type | Alphanumeric | No | 30 | Line type. 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) |
| premises | Alphanumeric | No | 60 | Identifies premises on a thoroughfare i.e. house name and/or number. Examples “24”, “Bleak House”. Although this field is optional, partners should send a complete and accurate address. If this field is not populated, then full use must be made of other address fields |
| thoroughfare | Alphanumeric | No | 55 | The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street. Although this field is optional, partners should send a complete and accurate address. If this field is not populated, then full use must be made of other address fields. |
| locality | Alphanumeric | No | 30 | Village or an area within a town and Town if possible. Although this field is optional, partners should send a complete and accurate address. If this field is not populated, then full use must be made of other address fields. |
| notify-email | Alphanumeric | No | The email address to notify when a status change occurs. Optional, but will reduce functionality if omitted. | |
| return-mode | Blank | No | See separate return-mode parameter document. | |
| return-format | Blank | Yes | See separate return-format parameter document. |
Output parameters
Return format of FAILED command:
<status_code>: <text_description>
Return format of SUCCESS command:
<status_code>: <text_description>
id: <id>
Cease a customer
Request
Method: POST
Description: Used to remove the requested number at BT’s TDM system.
| Parameter | Type | Required | Length | Description |
|---|---|---|---|---|
| command | Alphanumeric | Yes | Value must be “cease” | |
| username | Alphanumeric | Yes | aql username | |
| password | Alphanumeric | Yes | aql password | |
| number | Numeric | Yes | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| effective_date | Alphanumeric | Yes | 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 | Yes | The email address to notify when a status change occurs. Optional, but will reduce functionality if omitted. | |
| return-mode | Blank | No | return-mode parameter | |
| return-format | Blank | No | return-format parameter |
Output parameters
Return format of FAILED command:
<status_code>: <text_description>
Return format of SUCCESS command:
<status_code>: <text_description>
id: <id>
Modify a customer
Request
Method: POST
Description: Used to modify the requested number’s customer details at BT’s TDM system.
| Parameter | Type | Required | Length | Description |
|---|---|---|---|---|
| command | Alphanumeric | Yes | Value must be “modify” | |
| username | Alphanumeric | Yes | aql username | |
| password | Alphanumeric | Yes | aql password | |
| number | Numeric | Yes | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| postcode | Alphanumeric | Yes | 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 | Alphanumeric | Yes | 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 | Yes | 50 | Name of the customer (if residential) or business Name |
| title | Alphanumeric | No | 20 | Title of the customer |
| forename | Alphanumeric | No | 20 | Forename of the customer |
| honours | Alphanumeric | No | 30 | Honours of the customer |
| business_suffix | Alphanumeric | No | 50 | Business suffix |
| line_type | Alphanumeric | No | 30 | Line type. 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). |
| premises | Alphanumeric | No | 60 | Identifies premises on a thoroughfare i.e. house name and/or number. Example 24 and/or Bleak House. Although this field is optional, partners should send a complete and accurate address. If this field is not populated, then full use must be made of other address fields. |
| thoroughfare | Alphanumeric | No | 55 | The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street. Although this field is optional, partners should send a complete and accurate address. If this field is not populated, then full use must be made of other address fields. |
| locality | Alphanumeric | No | 30 | Village or an area within a town and Town if possible. Although this field is optional, partners should send a complete and accurate address. If this field is not populated, then full use must be made of other address fields. |
| notify-email | Alphanumeric | No | The email address to notify when a status change occurs. Optional, but will reduce functionality if omitted. | |
| return-mode | Blank | No | See separate return-mode parameter document. | |
| return-format | Blank | Yes | See separate return-mode parameter document. |
Output parameters
Return format of FAILED command:
<status_code>: <text_description>
Return format of SUCCESS command:
<status_code>: <text_description>
id: <id>
Export number
Request
Used to initiate an export to another carrier at BT’s TDM system.
| Parameter | Type | Required | Length | Description |
|---|---|---|---|---|
| command | Alphanumeric | Yes | Value must be “export” | |
| username | Alphanumeric | Yes | aql username | |
| password | Alphanumeric | Yes | aql password | |
| number | Numeric | Yes | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| postcode | Alphanumeric | Yes | 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 | Alphanumeric | Yes | 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 | Yes | CUPID of importing CP | |
| return-mode | Blank | No | See separate return-mode parameter document | |
| return-format | Blank | No | See separate return-mode parameter document |
Output parameters
Return format of FAILED command:
<status_code>: <text_description>
Return format of SUCCESS command:
<status_code>: <text_description>
id: <id>
Import number
Request
Used to confirm the import of a number from other carrier at BT’s TDM system.
| Parameter | Type | Required | Length | Description |
|---|---|---|---|---|
| command | Alphanumeric | Yes | Value must be “import” | |
| username | Alphanumeric | Yes | aql username | |
| password | Alphanumeric | Yes | aql password | |
| number | Numeric | Yes | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| cp_identifier | Numeric | Yes | CUPID of exporting CP | |
| postcode | Alphanumeric | Yes | 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 | Alphanumeric | Yes | 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 | Yes | 50 | Name of the customer (if residential) or business Name |
| title | Alphanumeric | No | 20 | Title of the customer |
| forename | Alphanumeric | No | 20 | Forename of the customer |
| honours | Alphanumeric | No | 30 | Honours of the customer |
| business_suffix | Alphanumeric | Yes | 50 | Business suffix |
| line_type | Alphanumeric | Yes | 30 | Line type. 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). |
| premises | Alphanumeric | Yes | 60 | Identifies premises on a thoroughfare i.e. house name and/or number. Example 24 and/or Bleak House. Although this field is optional, partners should send a complete and accurate address. If this field is not populated, then full use must be made of other address fields. |
| thoroughfare | Alphanumeric | Yes | 55 | The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street. Although this field is optional, partners should send a complete and accurate address. If this field is not populated, then full use must be made of other address fields. |
| locality | Alphanumeric | Yes | 30 | Village or an area within a town and Town if possible. Although this field is optional, partners should send a complete and accurate address. If this field is not populated, then full use must be made of other address fields. |
| return-mode | Blank | No | See separate return-mode parameter document. | |
| return-format | Blank | Yes | See separate return-mode parameter document. |
Output parameters
Return format of FAILED command:
<status_code>: <text_description>
Return format of SUCCESS command:
<status_code>: <text_description>
id: <id>
Get last ID by number
Request
Returns the last ID associated with the requested phone number
| Parameter | Type | Required | Length | Description |
|---|---|---|---|---|
| command | Alphanumeric | Yes | Value must be “getlastidbynumber” | |
| username | Alphanumeric | Yes | aql username | |
| password | Alphanumeric | Yes | aql password | |
| number | Numeric | Yes | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| return-mode | Numeric | No | See separate return-mode parameter document | |
| return-format | Numeric | No | See separate return-mode parameter document |
Output parameters
Return format of FAILED command:
<status_code>: <text_description>
Return format of SUCCESS command:
<status_code>: <text_description>
id: <id>
Get record by ID
Request
Returns all attributes of requested record
| Parameter | Type | Required | Length | Description |
|---|---|---|---|---|
| command | Alphanumeric | Yes | Value must be “getrecordbyid” | |
| username | Alphanumeric | Yes | aql username | |
| password | Alphanumeric | Yes | aql password | |
| number | Numeric | Yes | 15 | Telephone Number. Must start with 0 e.g. 01242111222 |
| id | Numeric | Yes | Record ID number | |
| return-mode | Blank | No | See separate return-mode parameter document | |
| return-format | Blank | No | See separate return-mode parameter document |
Request
<status_code>: <text_description>
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>
Record status
| Status | Description |
|---|---|
| READY | Data captured and ready to send. All 999 update requests are collated and sent in batches periodically |
| PENDING | Data submitted |
| COMPLETE | Request completed |
| FAILED | Request failed |
Responses
Return codes
You can see all possible return codes in our 999 API return codes reference.
Status codes
| Status | Description |
|---|---|
| 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 STILL 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 |