999 Hosted Number Ranges
Introduction
This API is designed to allow partners who have their number ranges hosted with aql to update their interface with BT's 999 system. This will provide an easy method for the update of BT's 999 record details for our customers.
Interface
Interface Protocols
The protocol presented is HTTPS. All the API methods will be executed by a standard POST request of the HTTPS protocol.
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: Used to activate a number with associated customer details at BT's TDM system.
URL: https://999.aql.com/matilda/ActivateCustomer
Method: POST
| Parameter |
Type |
Required |
Length |
Description |
|
username
|
Alphanumeric
|
Yes
|
aql
|
999 username
|
|
password
|
Alphanumeric
|
Yes
|
aql
|
999 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 following format: 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
|
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
|
|
thoroughfare
|
Alphanumeric
|
No
|
55
|
The thoroughfare name and type. For example, Byron Close, Suffolk Lane, and High Street
|
|
locality
|
Alphanumeric
|
No
|
30
|
Village or an area within a town and town if possible
|
Output Parameters
| Parameter |
Value |
Description |
|
id
|
Numeric
|
ID of created record
|
Modify Customer: Remove
Request: Used to remove the requested number at BT's TDM system.
URL: https://999.aql.com/matilda/CeaseCustomer
Method: POST
| Parameter |
Type |
Required |
Length |
Description |
|
username
|
Alphanumeric
|
Yes
|
|
999 username
|
|
password
|
Alphanumeric
|
Yes
|
|
999 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)
|
Output Parameters
| Parameter |
Value |
Description |
|
id
|
Numeric
|
ID of removed record
|
Modify Customer: Modify
Request: Used to modify the requested number at BT's TDM system.
URL: https://999.aql.com/matilda/ModifyCustomer
Method: POST
| Parameter |
Type |
Required |
Length |
Description |
|
username
|
Alphanumeric
|
Yes
|
|
999 username
|
|
password
|
Alphanumeric
|
Yes
|
|
999 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 following format: 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
|
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
|
|
thoroughfare
|
Alphanumeric
|
No
|
55
|
The thoroughfare name and type. Examples: Byron Close, Suffolk Lane, and High Street.
|
|
locality
|
Alphanumeric
|
No
|
30
|
Village or an area within a town and town if possible
|
Output Parameters
| Parameter |
Value |
Description |
|
id
|
Numeric
|
ID of removed record
|
Export Number
Request: Use to initiate an export to another carrier at BT's TDM system.
URL: https://999.aql.com/matilda/ExportNumber
Method: POST
| Parameter |
Type |
Required |
Length |
Description |
|
username
|
Alphanumeric
|
Yes
|
|
aql 999 username
|
|
password
|
Alphanumeric
|
Yes
|
|
aql 999 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', e.g. 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
|
Output Parameters
| Parameter |
Value |
Description |
|
id
|
Numeric
|
ID of exported record
|
Import Number
Request: Used to confirm the import of a number from other carrier at BT's TDM system.
URL: https://999.aql.com/matilda/ImportNumber
Method: POST
| Parameter |
Type |
Required |
Length |
Description |
|
username
|
Alphanumeric
|
Yes
|
|
aql 999 username
|
|
password
|
Alphanumeric
|
Yes
|
|
aql 999 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', e.g. 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
|
|
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. E.g. 24 and/or Bleak House
|
|
thoroughfare
|
Alphanumeric
|
No
|
55
|
The thoroughfare name and type, e.g. Byron Close, Suffolk Lane, and High Street
|
|
locality
|
Alphanumeric
|
No
|
30
|
Village or an area within a town and town if possible
|
Output Parameters
| Parameter |
Value |
Description |
|
id
|
Numeric
|
ID of imported record
|
Get Record IDs by Number
Request: Returns the ID numbers of all records associated with the requested phone number. Record ID numbers will be ordered from most recent to oldest.
URL: https://999.aql.com/matilda/GetRecordIDsByNumber
Method: POST
| Parameter |
Type |
Required |
Length |
Description |
|
username
|
Alphanumeric
|
Yes
|
|
aql 999 username
|
|
password
|
Alphanumeric
|
Yes
|
|
aql 999 password
|
|
number
|
Numeric
|
Yes
|
15
|
Telephone number. Must start with 0, e.g. 01242111222
|
Response
| Parameter |
Value |
Description |
|
id
|
Alphanumeric
|
List of record IDs separated by commas, ordered by most recent record to oldest, e.g. '135,141,156'
|
Get Record by ID
Request: Used to activate a number with associated customer details at BT's TDM system.
URL: https://999.aql.com/matilda/ActivateCustomer
Method: POST
| Parameter |
Value |
Description |
|
id
|
Numeric
|
ID of record
|
|
created
|
Alphanumeric
|
Date and time of when the request was made to aql 999. Format: YYYY-MM-DD HH:MM.SS.mmmmmm
|
|
command
|
Alphanumeric
|
Command (A, C, M, E, I)
|
|
status
|
Alphanumeric
|
Record status (see below)
|
|
postcode
|
Alphanumeric
|
Customer's postcode
|
|
effective_date
|
Alphanumeric
|
Date on which the command associated with the listing is to be executed. Format used is YYYY-MM- DD (where Y = Year, M = Month & D = Day)
|
|
surname
|
Alphanumeric
|
Name of the customer
|
|
title
|
Alphanumeric
|
Title of the customer
|
|
forename
|
Alphanumeric
|
Forename of the customer
|
|
honours
|
Alphanumeric
|
Honours of the customer
|
|
business_suffix
|
Alphanumeric
|
Business suffix
|
|
line_type
|
Alphanumeric
|
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
|
Identifies premises on a thoroughfare i.e. house name and/or number. E.g. 24 and/or Bleak House
|
|
thoroughfare
|
Alphanumeric
|
The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street
|
|
locality
|
Alphanumeric
|
Village or an area within a town and town if possible
|
|
cp_identifier
|
Numeric
|
CUPID
|
|
ret_code
|
Numeric
|
Return code after processing record
|
|
err_msg
|
Alphanumeric
|
Any error message received
|
Response 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
|
