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 address based, using an Openreach address key or UPRN, or copper line based , using an associated telephone number for a line or its access line id.

• For address based checks, A gold Openreach NAD key and district code is required (obtained via an address search) or a Unique Property Reference Number (UPRN). 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	A string identifier of the product offering qualification item
productOfferingQualificationItem.product.place.id	A15104999999	Openreach Gold NAD key.
productOfferingQualificationItem.product.place.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"
    }

An alternative to an Openreach NAD key and district code is a UPRN like so (note the changed referred type)

{
	"id": "100011473939",
	"role": "install address",
	"@referredType": "btUPRNLocationReference"
}

For a line based check (using an access line id or directory number) the place object is replaced by a product relationship to an existing realizing service like so

	"productRelationship": [
		{
			"relationshipType": "isTargeted",
			"product": {
				"realizingService": [
					{
						"id": "C000034389999",
						"name": "Access Line"
					}
				]
			}
		}
	]

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. 

Presence of a product offering in the response does not mean that the offering is available to order. Particular attention needs to be paid to any associated availability flags or indication of fibre priority as these can indicate that, whilst a particular technology is generally available, there might be an issue with compatibility or capacity or that a FTTP product should be ordered in preference to an FTTC product.

FTTP productOfferingQualificationItem objects also  include lists of any  optical network terminal(s) (ONT) already installed at a location which may have services on which can be migrated or spare ports on when a new service can be activated.

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  (Product Characteristic)	SOGEA	Indication of the  access network technology the offering is based on (ADSL,SOADSL, FTTC, SOGEA, FTTP).
productMinimumGuaranteedSpeed (Product Characteristic)	55.2	You need to provide this information (it's in Mbps) in your order as the quoted guaranteed minimum speed for this product at time of sale.
productOfferingQualificationItem.productOffering.id	SOGEA 80_20M	Description of product offering in terms of access technology and download and upload speed. You'll convert this value to an product offering code using the product catalogue. For reference, this product would be E0000432.

FTTP

Additionally for FTTP the realizingResource array indicates working and spare ports on existing FTTP Optical Network Terminations (ONT) together with reference numbers. When placing orders for existing ONTs ONT reference number and port is required in the order.

Property	Value (example)	Notes
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 and has a service which could be migrated. Spare indicates the port can be used to activate a new broadband service.

Helpful values in determining  product availability

Property	Value (example)	Notes
REASONCODE (Product Characteristic)	A	This is only meaningful for line based checks and refers to existing broadband or incompatible technologies on a   copper  line. Incompatible products are only an issue when dealing with working rather than stopped lines. The existing broadband on a working copper line determines how broadband migrations for FTTC/ADSL/SoGEA/SoADSL are managed.  Can be returned blank if information is not available. See table of reason codes below for more information. For address based checks this is populated with Z by default.
AVAILABILITY_FLAG (Product Characteristic)	Y	The availability flag is only used for FTTC and SoGEA.  It is not used for ADSL, SoADSL or FTTP. This flag can have the values  "Y","N","W","E" , "P"  or "".  Given WLR Stop Sell, the typical values for FTTC are "N" or "".  The blank response for the availability flag is indicative of speed issues where VDSL is not a viable solution.  In these cases the only product offering likely to have a productMinimumGuaranteedSpeed is the 0.5 M low speed offering. "W" indicates that there is a waiters list for new FTTC/SoGEA provide orders and "E" indicates that FTTC/SoGEA is only available by exception as the premises is served by a fibre priority exchange."P" means  availability is planned for a future date.
		FTTP replaces this availability flag with three flags to indicate general availability of FTTP (new ONT available) and also the presence of  ONTs in the premises with spare ports or the ability to be upgraded to a multiport ONT (existing ONT available) plus whether there is existing working FTTP services which can be migrated (CP transfer or WLTO available).
FTTPNEWONTAVAILABLE (Product Characteristic)	Y	Indicates whether a new or additional ONT can be provided. The values are "Y" (Yes), "N" (No) , "P" (Planned)  and " W" (Waiters list - capacity currently unavailable)
FTTPCPTRANSFERORWLTOAVAILABLE (Product Characteristic)	Y	Is there an existing FTTP product on a working port which could be migrated or taken over? The values can be "Y" (Yes) or "N" (No).
FTTPEXISTINGONTAVAILABLE (Product Characteristic)	N	Is there a spare data port on an existing ONT which can can be used to provide a new FTTP product instance (or can a single port ONT be swapped out for a multiport ONT? The values can be "Y" (Yes) , "N" (No) or "P" (Planned)
FTTPPriorityExchange (Product Characteristic)	N	If FTTP is available does it take priority over other products such as SoGEA? The values can be "Y" (Yes) or "N" (No).

Managed Install required?

FTTP

• No existing ONT,  no ports available on an existing ONT or require an additional ONT located elsewhere? You'll need to order a new  ONT or multiport 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/FTTC

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 and Associated notes

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