APIs and documentation

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 a customer

Request

Description : Used to activate a number with associated customer details at BT’s TDM system.

ParameterTypeRequiredLengthDescription
commandAlphanumericYes Value must be "activate"
usernameAlphanumericYes aql username
passwordAlphanumericYes aql 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_dateAlphanumericYesRequired 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. 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
thoroughfareAlphanumericNo55 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.
localityAlphanumericNo30 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-emailAlphanumericNo The email address to notify when a status change occurs. Optional, but will reduce functionality if omitted.
return-modeBlankNo return-mode parameter
return-formatBlankYes 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>


Cease a customer

Request

Method : POST

Description : Used to remove the requested number at BT’s TDM system.

ParameterTypeRequiredLengthDescription
commandAlphanumericYes Value must be "cease"
usernameAlphanumericYes aql username
passwordAlphanumericYes aql 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)
notify-emailAlphanumericNo The email address to notify when a status change occurs. Optional, but will reduce functionality if omitted.
return-modeBlankNo return-mode parameter
return-formatBlankNo 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>

Modify a customer

Request

Method: POST

Description: Used to modify the requested number’s customer details at BT’s TDM system

ParameterTypeRequiredLengthDescription
commandAlphanumericYes Value must be "modify"
usernameAlphanumericYes aql username
passwordAlphanumericYes aql 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. 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.
thoroughfareAlphanumericNo55 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.
localityAlphanumericNo30 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-emailAlphanumericNo The email address to notify when a status change occurs. Optional, but will reduce functionality if omitted.
return-modeBlankNo return-mode parameter
return-formatBlankNo 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>

Export number

Request

Used to initiate an export to another carrier at BT's TDM system

ParameterTypeRequiredLengthDescription
commandAlphanumericYes Value must be "export"
usernameAlphanumericYes aql username
passwordAlphanumericYes aql 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
return-modeBlankNo return-mode parameter
return-formatBlankNo 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>

Import number

Request

Used to confirm the import of a number from other carrier at BT’s TDM system.

ParameterTypeRequiredLengthDescription
commandAlphanumericYes Value must be "import"
usernameAlphanumericYes aql username
passwordAlphanumericYes aql 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 (if residential) or business name
titleAlphanumericNo20 Title of the customer
forenameAlphanumericNo20 Forename of the customer
honoursAlphanumericNo30 Honours of the customer
business_suffixAlphanumericYes50 Business suffix
line_typeAlphanumericYes30 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)
premisesAlphanumericYes60 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.
thoroughfareAlphanumericYes55 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.
localityAlphanumericYes30 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-modeBlankNo return-mode parameter
return-formatBlankNo 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>

Get last ID by number

Request

Returns the last ID associated with the requested phone number

ParameterTypeRequiredLengthDescription
commandAlphanumericYes Value must be "getlastidbynumber"
usernameAlphanumericYes aql username
passwordAlphanumericYes aql Password
numberNumericYes15 Telephone Number. Must start with 0 e.g. 01242111222
return-modeBlankNo return-mode parameter
return-formatBlankNo 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>

Get record by ID

Request

Returns all attributes of requested record

ParameterTypeRequiredLengthDescription
commandAlphanumericYes Value must be "getrecordbyid"
usernameAlphanumericYes aql username
passwordAlphanumericYes aql Password
numberNumericYes15 Telephone Number. Must start with 0 e.g. 01242111222
idNumericYes Record ID number
return-modeBlankNo return-mode parameter
return-formatBlankNo return-mode parameter
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
StatusDescription
READYData captured and ready to send. All 999 update requests are collated and sent in batches periodically
PENDINGData submitted
COMPLETERequest completed
FAILEDRequest failed

Responses

Return codes

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

Status codes

StatusDescription
200OK
400BAD REQUEST
401AUTHENTICATION ERROR
500INTERNAL SYSTEM ERROR
600INVALID COMMAND
67001NUMBER NOT VALID OR PROVIDED
67013NUMBER NOT ON ACCOUNT
67008PREVIOUS COMMAND STILL PENDING
67009NUMBER ALREADY ACTIVE. CANNOT ACTIVATE AGAIN
67010NUMBER MUST FIRST BE ACTIVATED USING THE ACTIVATE COMMAND
67004SURNAME NOT PROVIDED
67002POSTCODE NOT PROVIDED
67003EFFECTIVE_DATE NOT PROVIDED
67005LINE_TYPE NOT PROVIDED
67006CP_IDENTIFIER NOT PROVIDED
67011NUMBER CANNOT BE CEASED BECAUSE IT IS NOT ALREADY ACTIVE
67007ID NOT PROVIDED
67012INVALID ID FOR THAT NUMBER

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