APIs and documentation

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 OK404 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
ParameterTypeRequiredLengthDescription
usernameAlphanumericYes aql 999 username
passwordAlphanumericYes aql 999 password
numberNumericYes15 Telephone Number. Must start with 0 e.g. 01242111222
postcodeAlphanumericYes8 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_dateAlphanumericYes 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)
surnameAlphanumericYes50 Name of the customer if residential or business Name
titleAlphanumericNo20 Title of the customer
forenameAlphanumericNo20 Forename of the customer
honoursAlphanumericNo30 Honours of the customer
business_suffixAlphanumericNo50 Business suffix
line_typeAlphanumericNo30 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)
premisesAlphanumericNo60 Identifies premises on a thoroughfare i.e. house name and/or number. Example: 24 and/or Bleak House
thoroughfareAlphanumericNo55 The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street.
localityAlphanumericNo30 Village or an area within a town and Town if possible
Output parameters
ParameterValueDescription
idNumericID of created record

Modify customer

Request

Used to remove the requested number at BT's TDM system.

URL
https://999.aql.com/matilda/CeaseCustomer
Method
POST
ParameterTypeRequiredLengthDescription
usernameAlphanumericYes aql 999 username
passwordAlphanumericYes aql 999 password
numberNumericYes15 Telephone Number. Must start with 0 e.g. 01242111222
effective_dateAlphanumericYes 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
ParameterValueDescription
idNumericID of removed record

Modify customer

Request

Used to modify the requested number's customer details at BT's TDM system.

URL
https://999.aql.com/matilda/ModifyCustomer
Method
POST
ParameterTypeRequiredLengthDescription
usernameAlphanumericYes aql 999 username
passwordAlphanumericYes aql 999 Password
numberNumericYes15 Telephone Number. Must start with 0 e.g. 01242111222
postcodeAlphanumericYes8 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_dateAlphanumericYes 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)
surnameAlphanumericYes50 Name of the customer
titleAlphanumericNo20 Title of the customer
forenameAlphanumericNo20 Forename of the customer
honoursAlphanumericNo30 Honours of the customer
business_suffixAlphanumericNo50 Business suffix
line_typeAlphanumericNo30 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)
premisesAlphanumericNo60 Identifies premises on a thoroughfare i.e. house name and/or number. Example 24 and/or Bleak House
thoroughfareAlphanumericNo55 The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street
localityAlphanumericNo30 Village or an area within a town and Town if possible
Output parameters
ParameterValueDescription
idNumericID of modified 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
ParameterTypeRequiredLengthDescription
usernameAlphanumericYes aql 999 username
passwordAlphanumericYes aql 999 Password
numberNumericYes15 Telephone Number. Must start with 0 e.g. 01242111222
postcodeAlphanumericYes8 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_dateAlphanumericYes 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_identifierNumericYes CUPID of importing CP
Output parameters
ParameterValueDescription
idNumericID of experted 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
ParameterTypeRequiredLengthDescription
usernameAlphanumericYes aql 999 username.
passwordAlphanumericYes aql 999 Password
numberNumericYes15 Telephone Number. Must start with 0 e.g. 01242111222
cp_identifierNumericYes CUPID of exporting CP
postcodeAlphanumericYes8 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_dateAlphanumericYes 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)
surnameAlphanumericYes50 Name of the customer
titleAlphanumericNo20 Title of the customer
forenameAlphanumericNo20 Forename of the customer
honoursAlphanumericNo30 Honours of the customer
business_suffixAlphanumericNo50 Business suffix
line_typeAlphanumericNo30 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)
premisesAlphanumericNo60 Identifies premises on a thoroughfare i.e. house name and/or number. Example 24 and/or Bleak House
thoroughfareAlphanumericNo55 The thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street
localityAlphanumericYes30 Village or an area within a town (and town if possible)
Output parameters
ParameterValueDescription
idNumericID 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
ParameterTypeRequiredLengthDescription
usernameAlphanumericYes aql 999 username
passwordAlphanumericYes aql 999 Password
numberNumericYes15 Telephone Number. Must start with 0 e.g. 01242111222
Response
ParameterValueDescription
idAlphanumericList 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
ParameterTypeRequiredLengthDescription
usernameAlphanumericYes aql 999 username
passwordAlphanumericYes aql 999 password
numberNumericYes15 Telephone Number. Must start with 0 e.g. 01242111222
idNumericYes Record ID number
Output parameters
ParameterValueDescription
idNumericID of record
createdAlphanumericDate and time of when the request was made to aql 999. Format: YYYY-MM-DD HH:MM.SS.mmmmmm
commandAlphanumericCommand. (A, C, M, E, I)
statusAlphanumericRecord status (see below)
postcodeAlphanumericCustomer’s postcode
effective_dateAlphanumericDate 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)
surnameAlphanumericName of the customer
titleAlphanumericTitle of the customer
forenameAlphanumericForename of the customer
honoursAlphanumericHonours of the customer
business_suffixAlphanumericBusiness suffix
line_typeAlphanumericLine 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)
premisesAlphanumericIdentifies premises on a thoroughfare i.e. house name and/or number. Example 24 and/or Bleak House
thoroughfareAlphanumericThe thoroughfare name and type Examples: Byron Close, Suffolk Lane, and High Street
localityAlphanumericVillage or an area within a town and Town if possible
cp_identifierNumericCUPID
ret_codeNumericReturn code after processing record
err_msgAlphanumericAny error message received
Response status
StatusDescription
READYData captured and ready to send. All 999 update requests are collated and sent in batches periodically.
PENDINGData submitted
COMPLETERequest completed
FAILEDRequest failed

Return codes

You can see all possible return codes in our 999 API return codes reference.


Back to Documentation and APIs

Follow us on Twitter

Like us on Facebook

Connect to us on LinkedIn

Where we are

aql
13-15 Hunslet Road
Leeds
LS10 1JQ
Telephone 01133 20 30 40