Getting Access

Access to this API requires to have an active Inbound Contact service as well as the Call Traffic Controller feature enable. If these pre-requisites are met, then in order to obtain the API credentials necessary to use to this API send a mail to AskCTD@bt.com .

The API credentials provided will need to be put in the APIGW-API-Key header in the API requests

Concepts

This API uses the following concepts: end points; access numbers; announcements and routing plans. They are each described in the next section

End Points

Phone end point

A phone end point is a public telephone number used to terminate Inbound Contact Global calls (they are also often referred to as Indirect, PSTN, DID, Off-Net and Switched). The phone end points are unique and can only belong to a single Inbound Contact Global Corporate ID.

A phone end point consists of:

  • Phone number e.g. 442072223333
  • The number’s associated ITU country code e.g. 44
  • A location ID (F+7 digits) that is assigned to the phone end point when it is created in the system

Supported actions using this API on Phone End Points are Create, Update, Get and Delete

Physical end point

A physical end point refers to a dedicated connection to a customer’s premises or another BT contact product. A physical end point cannot be provisioned via the Controller API and requires an order to be submitted on behalf of the Inbound Contact Global customer.

A physical end point can be one of the following:

  • SIP DAL – Connection to the customer using IP Connect global or other MPLS product
  • Internet DAL – Connection to a customer’s IP address or Fully Qualified Domain Name via the Internet
  • TDM DAL – Traditional Voice Dedicated Access Line such as an E-1 or T-1

In Controller, the physical end point is unique to the customer and is designated by:

  • Switch / Trunk ID (e.g. 323/1111)
  • Location ID (F+7 digits) that is assigned to the physical end point when it is created in the system
  • Terminating country
  • Termination type (SIP, Internet, TDM)

The supported action using this API on Physical End Points is Get. 

Creating, Deleting or Updating Physical End Points happens through the standard ordering process for Inbound Contact.

Logical end point

A logical end point is the terminating digits sent to the customer’s equipment when a call is sent to a physical end point. These digits are referred to as DNIS (Dialled Number Identification Service) Digits and can be any value up to 16 digits in length and are unique within a corporate ID. A physical end point can have many logical end points associated with it.

A logical end point consists of:

  • Parent Switch/Trunk
  • DNIS Digits (up to 16 Digits)

Supported actions using this API on Physical End Points are Create, Update, Get and Delete.

Access Numbers and Announcements

Access number

An access number is the dialled number assigned to the customer that can be used to reach the customer. Access numbers vary by country and number type and are the originating number that defines an inbound call as it enters the Inbound Contact Global network.

An access number consists of:

  • Access number (dialled number in E.164 Format)
  • Network address (Point of entry to the BT Network, in some cases it might be the same value as the access number)
  • Application ID (A 10 digit identifier that is used by the network to identify the current active routing plan)
  • Country of origin
  • Inbound access type (toll-free, caller pays, shared cost etc)

Access number APIs allow users to retrieve the list of access numbers or a specific access number. Creation, update or deletion of an Access number follows the normal ordering process for Inbound Contact.

Access number set

An Access Number Set is a group of Access Numbers that can be mapped to Routing Plans that become active when the Set is triggered. Access Number Sets are used to build Business Continuity scenarios and facilitate migrations or management of groups of numbers.

Access Number Sets are optional, routing plans can still be activated against individual numbers as needed.

Note the following features:

  • An Access Number Set can consist of up to 2,000 entries.
  • Multiple Access Number Sets can be created under a corporation.
  • An Access Number can be in multiple Access Number Sets.

Announcements

An announcement is a network-based recording that can be used to play a message during a call’s transmission to its destination. It is incorporated within a routing plan and can be followed by another routing plan feature, a customer end point or a release end point (disconnect). Announcements are also used as prompts for some routing plan features.

Announcement APIs allow users to retrieve the list of announcements or the name of an individual announcement. Content of the actual announcement is not available to be retrieved through the API.

DNIS table entries

A DNIS (Dialled Number Identification Service) table is an addition to a Logical End Point that provides a method to assign different DNIS digits to the Access Number dialed by the caller.

DNIS Tables allow the same routing logic to be applied to multiple Access Numbers. A DNIS Table has a primary DNIS Digit entry just as every Logical End Point. The primary DNIS Digit is used as a "Default" DNIS when no matching entry on a DNIS table is found during the call.

Screening list

A screening list is a list of calling numbers (CLI / ANI in E.164 format) or calling number prefixes that are included for use in a screening plan.

Screening plans allow customers to block nuisance callers, create allowed caller lists or restrict dialling in geographic areas before the call is routed to its destination.

  • Customers with existing screening plans can use this API to add or remove entries from the screening list.
  • Each screening list entry include CLI or CLI prefix and optionally a start and finish date for inclusion of the number on the screening list.

     

Routing Plans

A routing plan consists of the routing logic associated with an access number’s application ID. A routing plan can be dedicated to a specific access number or can be a special type that is shared by multiple access numbers (corporate plan). Routing plans can be simple point-to-point routing where every call to an access number always goes to the same phone or logical end point or use one or more advanced routing plan features which can also be combined with each other to route calls to multiple destinations.

The available features are:

  • NOFEATURE – Simple point-to-point routing

  • Call distribution – Load balancing feature that routes calls to multiple destinations in a configurable ratio

  • Uniform load distribution – Routes calls evenly between destinations until a configurable simultaneous call threshold is met

  • Origin-dependent routing – Routes calls based on the CLI (Calling Line Identity)

  • Time-dependent routing – Routes calls base on the time of day, day of week or calendar date

  • Menu routing – Basic IVR feature with prompts and routes based on caller-entered digits

  • PIN routing – Prompts callers to enter PIN which is validated against a list of PINs before the call is sent to a destination

Routing plans can be active or inactive. A routing plan’s status is determined by whether or not it is currently listed as the active plan for a specific access number. Routing plans are activated by specifying the access number and the name of its new active routing plan.

Routing plans can be activated immediately upon command submission or scheduled in the future (using the GMT time zone). Multiple activations for a routing plan can be scheduled at a time.

For example, “Routing plan 1” can be scheduled to activate at 1700 GMT on 1-Jan and at the same time “Routing plan 2” can be scheduled to activate at 0900 GMT 4-Jan. This is useful for pre-planned staff holidays, outages or other events.

The Routing plan APIs allow to retrieve the routing plans, update routing plans and activate routing plans. 

Creating new routing plans or deleting them needs to be done through the call traffic controller GUI.

Back to top