Product And Network Availability

Introduction

Use this API to choose an appropriate Broadband One product offering based on the access technologies and speeds available at a location or for a line.

To see how this API forms part of the wider Broadband One order process, click the diagram below.

 

This tutorial will show how to:

• Find the right Broadband One product offering, and
• For FTTP,  whether there's a usable data port on an existing optical network termination point at a location or co-located with a copper line.

Request Method & URI

POST https://api.wholesale.bt.com/hubco/tmf/productOfferingQualification/v4/productOfferingQualification

Request Entity-Body

Product availability checks can be made for a premises using an address key or the identity of a copper line located at a premises.

• For address based checks, A gold Openreach NAD key and district code is required (obtained via an address search). This is useful for new line provide scenarios and will indicate which technologies and speeds are likely for the location;
• For line based checks, a telephone number for an Openreach line (Directory Number) or access line ID is required (access line ids for lines can be found using a gold NAD key to check line availability). This is useful for stopped line starts, migrations between providers and/or product offerings on a copper line or for migration from copper to fibre. Line based checks provide additional copper line related information required for migration orders showing the migration scenario which applies (BTW ADSL to BTW SoGEA etc).

An address based check would use the following attributes (as an example)

Property	Value (example)	Notes
productOfferingQualificationItem.id	74	Any number.
place.id	A15104999999	Openreach Gold NAD key.
districtId	LS	Openreach district ID.
relatedParty.id	CUG5023769999	Your business' BT Wholesale CUG ID.

{
  "@type": "btProductOfferingQualification",
  "instantSyncQualification": true,
  "productOfferingQualificationItem": [
    {
      "id": "74",
      "action": "add",
      "product": {
        "@type": "Product",
        "productOffering": {
          "id": "BroadbandOne",
          "@referredType": "btProductOfferingFamily"
        },
        "place": [
          {
            "id": "A90000423408",
            "districtId": "NI",
            "role": "install address",
            "@referredType": "btNADLocationReference"
          }
        ]
      },
      "@type": "btProductOfferingQualificationItem"
    }
  ],
  "provideAlternative": true,
  "provideOnlyAvailable": true,
  "provideUnavailabilityReason": false,
  "relatedParty": [ 
    {
        "id": "CUG5023768826",
        "role": "BtCug",
        "@type": "BTRelatedParty",
        "@referredType": "Customer"
    }

Response Entity-Body

This truncated response shows example FTTP and SOGEA options. Each available product offering (a combination of technology and speed) is shown individually with their respective attributes and characteristics.

FTTP productOfferingQualificationItem objects include optical network terminal (ONT) availability.

Below this you'll find an explanation of relevant attributes and characteristics which are relevant when placing the Broadband One order.

{
    "expirationDate": "2023-07-26T09:51:24.304Z",
    "instantSyncQualification": true,
    "productOfferingQualificationDate": "2022-11-05T18:18:24.304Z",
    "provideAlternative": true,
    "provideOnlyAvailable": true,
    "provideUnavailabilityReason": false,
    "qualificationResult": "qualified",
    "productOfferingQualificationItem": [
        {
            "id": "1",
            "product": {
                "place": [
                    {
                        "id": "A15104999999",
                        "role": "install address",
                        "@referredType": "btNADLocationReference"
                    }
                ],
                "productCharacteristic": [
                    {
                        "name": "AccessTechnology",
                        "value": "FTTP"
                    },
                    {
                        "name": "productHighDownloadSpeed",
                        "value": "147.2"
                    },
                    {
                        "name": "productLowDownloadSpeed",
                        "value": ""
                    },
                    {
                        "name": "productMinimumGuaranteedSpeed",
                        "value": "76"
                    },
                    {
                        "name": "productHighUploadSpeed",
                        "value": "27.6"
                    },
                    {
                        "name": "productLowUploadSpeed",
                        "value": ""
                    },
                    {
                        "name": "productMaximumUploadSpeed",
                        "value": ""
                    },
                    {
                        "name": "productMinimumUploadSpeed",
                        "value": ""
                    },
                    {
                        "name": "productMaximumDownloadSpeed",
                        "value": ""
                    },
                    {
                        "name": "productAdvertisedDownloadSpeed",
                        "value": "152"
                    },
                    {
                        "name": "productAdvertisedUploadSpeed",
                        "value": "28"
                    },
                    {
                        "name": "FTTPEXISTINGONTAVAILABLE",
                        "value": "N"
                    },
                    {
                        "name": "REASONCODE",
                        "value": "Z"
                    },
                    {
                        "name": "FTTPNEWONTAVAILABLE",
                        "value": "Y"
                    },
                    {
                        "name": "FTTPPriorityExchange",
                        "value": "N"
                    },
                    {
                        "name": "FTTPINSTALLPROCESS",
                        "value": "1 Stage"
                    },
                    {
                        "name": "FTTPCPTRANSFERORWLTOAVAILABLE",
                        "value": "Y"
                    }
                ],
                "productOffering": {
                    "id": "FTTP 160_30M",
                    "name": "FTTP"
                },
                "realizingResource": [
                    {
                        "id": "1",
                        "name": "ONT Data",
                        "value": {
                            "ONTREFNUMBER": "ONT0046482937",
                            "ONTFLOOR": "",
                            "ONTROOM": "",
                            "ONTPOSITION": "",
                            "BBUSTATUS": "Not Supplied",
                            "MAXSPEED": "Up to 1000",
                            "PORTLIST": {
                                "ONTPORT": [
                                    {
                                        "ONTPORTNUMBER": "1",
                                        "ONTPORTSTATUS": "Working",
                                        "ONTPORTTYPE": "Data",
                                        "VOICEWIRINGSTATUS": ""
                                    }
                                ]
                            }
                        },
                        "valueType": "object",
                        "@baseType": "ResourceRef",
                        "@type": "btONTResourceRef"
                    }
                ]
            },
            "@type": "btProductOfferingQualificationItem"
        },        {
            "id": "2",
            "product": {
                "place": [
                    {
                        "id": "A15104999999",
                        "role": "install address",
                        "@referredType": "btNADLocationReference"
                    }
                ],
                "productCharacteristic": [
                    {
                        "name": "AccessTechnology",
                        "value": "SOGEA"
                    },
                    {
                        "name": "productHighDownloadSpeed",
                        "value": "73.6"
                    },
                    {
                        "name": "productLowDownloadSpeed",
                        "value": "61.64"
                    },
                    {
                        "name": "productMinimumGuaranteedSpeed",
                        "value": "55.2"
                    },
                    {
                        "name": "productHighUploadSpeed",
                        "value": "18.4"
                    },
                    {
                        "name": "productLowUploadSpeed",
                        "value": "17.48"
                    },
                    {
                        "name": "productMaximumUploadSpeed",
                        "value": "18.99"
                    },
                    {
                        "name": "productMinimumUploadSpeed",
                        "value": "15.73"
                    },
                    {
                        "name": "productMaximumDownloadSpeed",
                        "value": "75.99"
                    },
                    {
                        "name": "productAdvertisedDownloadSpeed",
                        "value": "76"
                    },
                    {
                        "name": "productAdvertisedUploadSpeed",
                        "value": "19"
                    },
                    {
                        "name": "REASONCODE",
                        "value": "Z"
                    },
                    {
						"name": "AVAILABILITY_FLAG",
						"value": "Y"
					}
                ],
                "productOffering": {
                    "id": "SOGEA 80_20M",
                    "name": "SOGEA"
                }
            },
            "@type": "btProductOfferingQualificationItem"
        }
    ],
    "relatedParty": [
        {
            "id": "CUG5023769999",
            "role": "BtCug",
            "@type": "BTRelatedParty",
            "@referredType": "Customer"
        }
    ],
    "state": "done",
    "@type": "btProductOfferingQualification"
} 

Data from this response for placing an order

All access technologies

Property	Value (example)	Notes
AccessTechnology	SOGEA
productOffering.id	SOGEA 80_20M	You'll convert this value to an product offering code using the product catalogue. For reference, this product would be E0000432.
productMinimumGuaranteedSpeed	55.2	You need to provide this information (it's in Mbps) to your customer as part of the service contract. It shows the guaranteed minimum speed for this Broadband One product.

 

Migrations involving ADSL and FTTC

Property	Value (example)	Notes
REASONCODE	A	For ADSL and FTTC-based broadband service migrations, this indicates the pre-existing service associated with a line and whether it is currently provided by BT Wholesale (for a line based check). Some reason codes for a working line indicate an incompatible technology or where there is no broadband to migrate. A migration code of Z does not map to a value in an order - it simply indicates 'no issues', or, for a line based check, no pre-existing technology on the line that could affect the migration.

FTTP

The realizingResource array indicates working and spare ports on existing FTTP Optical Network Terminations (ONT) together with reference numbers..

Property	Value (example)	Notes
productOffering.id	FTTP 160_30M	You'll convert this value to an ecode using the product catalogue. For reference, this product would be E0000160.
productMinimumGuaranteedSpeed	38	You need to provide this information (it's in Mbps) to your customer as part of the service contract. It shows the guaranteed minimum speed for this Broadband One product.
FTTPINSTALLPROCESS	1 Stage	Indication of the installation process required to delivery a new or additional ONT. The alternative process to "1 Stage" is " KCI2 Assure".
ONTREFNUMBER	ONT0046482937	Required when you're using an existing ONT to provide Broadband One.
ONTPORTNUMBER	1	Required when you're using an existing ONT to provide Broadband One.
ONTPORTSTATUS	Working	Working denotes the port is currently in use. Spare indicates the port can be used without replacing/migrating an existing service.

Helpful values

Property	Value (example)	Notes
FTTPNEWONTAVAILABLE	Y	Indicates whether an additional ONT can be provided. Other values are N, and W (Waiters list - capacity currently unavailable)
FTTPCPTRANSFERORWLTOAVAILABLE	Y	Is there an existing FTTP product on a working port which could be migrated or taken over?.
FTTPEXISTINGONTAVAILABLE	N	Is there a spare data port on an existing ONT which can can be used to provide a new FTTP product instance?
FTTPPriorityExchange	N	If FTTP is available does it take priority over other products such as SoGEA? The values are either Y (Yes) or N (No).

Managed Install required?

FTTP

• No existing ONT, or no ports available on an existing ONT? You'll need to order a new or ONT - and a Managed Install.
• Otherwise - unless your end user requires installation/configuration support - the product can be self installed.

SOGEA/SOADSL

The line availability API indicates whether working or stopped lines (with their ids) are available to host a broadband product instance.

• Compatible line? Choose self install
• Otherwise, a new line is required  - and a Managed Install.

ADSL

Self install only.

Summary of Product Characteristic Names and Values

The following describes the product characteristics returned for various product offerings and possible values where there is an enumeration.

Name	Description	Values
AccessTechnology	Access technology associated with the product offering.	ADSL, FTTC, FTTP, SOADSL, SOGEA
productHighDownloadSpeed	Top end of the download speed estimate in Mbps.
productLowDownloadSpeed	Bottom end of the download speed estimate in Mbps.
productMaximumDownloadSpeed	Maximum possible  download speed for an unimpacted line of this length in Mbp
productMinimumGuaranteedSpeed	Minimum guaranteed access line speed in Mbps.
productAdvertisedDownloadSpeed	"Up to" download speed quoted for the product offering in Mbps.
productHighUploadSpeed	Top end of the upload speed estimate in Mbps
productLowUploadSpeed	Bottom end of the upload speed estimate in Mbps.
productMinimumUploadSpeed	The minimum expected upload speed in Mbps.
productAdvertisedUploadSpeed	"Up to" upload speed quoted for the product offering in Mbps.
REASONCODE	For line based checks the reason code indicates potential issues with the line or the technology currently associated with the line.	See table below
AVAILABILITY_FLAG	Indicates the availability of the relevant VDSL based technology.	Y= Available  N=Not available  E=Available for Exceptional Cases W= Waiting list P= Planned
FTTPPriorityExchange	Indicates whether the premises is to be served by FTTP in preference to any other access technologies available.	Y = As a fibre priority exchange, FTTP has priority over other products if available at the address N = The exchange is not in a current fibre priority programme
FTTPNEWONTAVAILABLE	Indicates whether it is possible to order a new additional ONT over any already present.	Y= Available  N= Not available W= Waiting for fibre capacity P= Planned
FTTPEXISTINGONTAVAILABLE	Indicates whether there is an existing spare port on an existing ONT.	Y= Available  N= Not available P= Planned
FTTPCPTRANSFERORWLTOAVAILABLE	Indicates whether there is a working FTTP based service on a port available for takeover or transfer/migration.	Y= Available  N= Not available
FTTPINSTALLPROCESS	This is derived by Openreach from serving network notes and  indicates number of stages/visits to be followed by engineer to perform an ONT Installation at the premises.	1 Stage  Indicates remote activation or single visit install.  KCI2 Assure Indicates external visit followed by order commitment and second visit to complete installation.
PREMISETYPE	Premises type information indicating single or multiple dwelling units for business or residential use. Relevant to FTTP installation.
SERVICENOTES	Serving network notes recorded by survey during  FTTP network roll out describing how the premises is to be served.
TMAMARKER	TMA (Traffic Management  Acts) Marker information. Indicates whether a notice or permit might be required for any street works associated with installing a new ONT.
TMANOTICEORPERMIT	TMA (Traffic Management Acts) Information. Indicates specifically whether notice has to be given or a permit applied for when planning any street works.	Notice Permit Undetermined
RECOMMENDEDMINIMUMLEADTIME	Minimum lead time in working days required for new ONT Install on a particular premise considering the TMA impact and ONT Install process.

Reason Codes and Their Meaning

Other Broadband One tutorials

There are tutorials for every API leading to, and including, placing the order:

• Address management
• Product and network availability
• Appointment management
• Order management and progress updates

Additional support

• Broadband One Product Handbook (BT Wholesale login required)
• Reference documentation
• Product catalogue
• Knowledge centre