999 API for 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 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 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 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 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 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 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 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

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 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
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 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, eg ‘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. Example: 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