# BT Wholesale Broadband One BT Wholesale provide a fibre-based managed service called Broadband One (BB1) that offers access to FTTP, SoGEA, SOGFAST and SOADSL. Access to this service is via a REST API based on TMF622. The Fibre Cafe has a connector to integrate with this API. ## Authentication OAuth 2.0 client credentials. Retailer ID (OFCOM RID), Billing Account Number and Cug ID are required. ## Address Search This is not currently supported by the connector but will be soon. ## Service Availability BB1 requires NAD and DistrictCode rather than UPRN - plus also requires RoBT when placing the orders. To ensure the same availability request can be used for querying BT and AltNets, it is suggested to send all address identifiers in the request e.g. ```json { "identifier": { "id": "10091846447", "type": "UPRN", "additionalIdentifiers": [ { "id": "A15104646284", "type": "NAD" }, { "id": "LS", "type": "DistrictCode" }, { "id": "R09598326361", "type": "ROBT" } ] } } ``` Address information is not provided in the response. ### Service Specifications When returning service specifications (product family/access technology) for an address, the available line profiles are returned in the 'serviceCharacteristics' field: ```json { "serviceSpecifications": [ { "id": "FTTP", "name": "WBCFTTP", "serviceCharacteristics": [ { "name": "LINE_PROFILE", "values": [ "120", "121" ] } ] } ] } ``` FTTP, SOGEA and SOADSL service specifications are supported. Existing line information is provided including type (copper or fibre) and current status. Stopped lines will have a stopped date. For fibre lines, ONT information includes: - ONT reference/ports - Description (port type) - Status (active or stopped) - Location (floor/room/position) The following information is not currently returned: - Installation types - Constraints - ENNI and handover point location - Service ready date Where there is no availability, granular reason codes are not provided (OTHER will be used). Where FTTP or SOGEA is available at the address, it will be likely that SOADSL is restricted and not available unless by exception. If SOADSL is returned in the serviceSpecifications, the response from BT Wholesale will have indicated it is available to be ordered - likely due to lack of alternative services at the address. If there is no availability returned for an address, the likelihood is that only FTTP On-demand is available and this cannot currently be ordered via the Fibre Cafe. ### Line Characteristics The 'lineCharacteristics' field for new or existing lines includes characteristics as defined on the [line characteristics](/pages/linecharacteristics) page: ```json { "line": { "lineCharacteristics": [ { "name": "MAX_DOWNSTREAM_MBPS", "value": "1000" } ] } } ``` This includes minimum and maximum downstream/upstream speeds (MIN|MAX_DOWNSTREAM_MBPS), availability date and minimum lead time (MINIMUM_LEAD_TIME) where returned by the BT Wholesale availability checker. Where there is an active pending cease (PENDING_CEASE) on a line, this is also indicated. A `MINIMUM_SITE_VISIT_REASON` line characteristic may be provided to indicate that a recommended level of Site Visit Reason will be required when ordering a service at this address. This can differ depending on the order type - e.g. a new provide may require 'Advanced' whereas an order on an existing line may only require 'Standard'. ### Installation Types BT Wholesale supports 1 or 2 stage installations (the latter also known as 'KCI2 Assure'): - **STANDARD**: When a standard appointment is necessary - **EXTENDED_STANDARD**: 2 stage installation 'KCI2 Assure'; refer to corresponding **INSTALL_NOTES** line characteristic for details Where installationType is not returned, an appointment is not required in the order. Note that this may change as the order progresses and an appointment may be required later - handled using the standard REAPPOINT/REAPPOINTED KCIs. ## Appointing When a managed install is required (e.g. for a new line or ONT), appointment timeslots can be listed and reserved. - Timeslots are classified as weekday, saturday, sunday and AM/PM - The default `SITE_VISIT_REASON` 'Standard' will be used where not provided as a service characteristic - A 'Premium' or 'Advanced' `SITE_VISIT_REASON` can be requested instead - this must be provided during appointment availability and reservation as well as in ordering Examples showing appointing requests include 'Premium' `SITE_VISIT_REASON`: Query Example ```curl ../available-appointments? supplier=BTWHOLESALEBB1& address={"id":"A00062300716","type": "NAD","additionalIdentifiers":[{"id":"TH","type":"DistrictCode"}]}& serviceSpecification={"id":"FTTP"}& serviceCharacteristics=[{"name":"SITE_VISIT_REASON","value":"Premium"}]& appointmentFromDate=2026-02-02& appointmentPurpose=PROVIDE ``` URL-encoded: ```curl ../available-appointments? supplier=BTWHOLESALEBB1& address=%7b%22id%22%3a%22A00062300716%22%2c%22type%22%3a%22NAD%22%2c%22additionalIdentifiers%22%3a%5b%7b%22id%22%3a%22TH%22%2c%22type%22%3a%22DistrictCode%22%7d%5d%7d& serviceSpecification=%7B%22id%22:%20%22FTTP%22%7D& serviceCharacteristics=%5B%0A%7B%0A%22name%22%3A%20%22SITE_VISIT_REASON%22%2C%0A%22value%22%3A%22Premium%22%0A%7D%0A%5D& appointmentFromDate=2026-02-02& appointmentPurpose=PROVIDE ``` Reserve Example ```json { "supplier": "BTWHOLESALEBB1", "address": { "id": "A00062300716", "type": "NAD", "additionalIdentifiers": [ { "id": "TH", "type": "DistrictCode" } ] }, "serviceSpecification": { "id": "FTTP" }, "serviceCharacteristics": [ { "name": "SITE_VISIT_REASON", "value": "Premium" } ], "purpose": "PROVIDE", "timeslot": { "timeslotStartDateTime": "2026-02-02T08:00:00Z", "timeslotEndDateTime": "2026-02-02T13:00:00Z" } } ``` ### Orders The following service characteristics are required when placing orders: - LINE_PROFILE : see below for values - END_USER_TYPE : type of end user - Business or Residential - CONTRACT_TERM : contract term in months These service characteristics are optional according to the order: - RETAILER_ID : unique identifier for the retailer provided by OFCOM - MINIMUM_SPEED : requested guaranteed minimum speed (realtime) - ECC_CHARGEBAND : Excess construction charges - see below for values - TRC_CHARGEBAND : Time related charges - see below for values - CARE_LEVEL : see below for values - STATIC_IP_REQUESTED : number of static IP addresses required: 1, 2, 6 - DN_PORT_NUMBER : phone number to port (SOGEA) - DN_PORT_DATETIME : date/time to port number (SOGEA) - SITE_VISIT_REASON : Standard, Premium or Advanced Amendment and cancellation requests can be made for inflight orders. There are limitations to what amendments can be done with the BB1 API - the following are permitted: - Change appointment - Update contact details - Update order notes - Change to ECC_CHARGEBAND or TRC_CHARGEBAND characteristics #### Line Profiles For BB1, line profiles map directly to an underlying product as follows: | Line Profile | Product variant | Ecode | | --- | --- | --- | | 111 | SOGEA 0.5_0.5M | E0000429 | | 112 | SOGEA 40_10M | E0000430 | | 113 | SOGEA 80_20M | E0000432 | | 121 | FTTP 80_20M | E0000021 | | 122 | FTTP 160_30M | E0000160 | | 123 | FTTP 330_50M | E0000174 | | 124 | FTTP 0.5_0.5M | E0000182 | | 125 | FTTP 40_10M | E0000183 | | 126 | FTTP 115_20M | E0000186 | | 127 | FTTP 550_75M | E0000187 | | 128 | FTTP 220_30M | E0000188 | | 129 | FTTP 1000_115M | E0000189 | | 131 | SOADSL 0.5M | E0001099 | | 132 | SOADSL 24M | E0001098 | #### Excess Construction Charges Charge bands to support extra construction charges - also known as upper cost bands for SOGEA/SOADSL services. The default chargeband where not provided is 0. | ECC_CHARGEBAND | FTTP | SOGEA | SOADSL | | --- | --- | --- | --- | | 0 | £0 | £0 | £0 | | 1 | £1 - £301 | £1 - £300 | £300 | | 2 | £301 - £601 | £301 - £600 | £600 | | 3 | £601 - £1001 | £601 - £1000 | £1000 | | 4 | £1001 - £3001 | £1001 - £1500 | £1500 | | 5 | £3001+ | £1500 - £3000 | £3000 | | 6 | n/a | £3000 - £99999 | £5000 | | 7 | n/a | n/a | £10000 | | 8 | n/a | n/a | £15000 | #### Time Related Charges Time related charges applies to copper-based orders (SOGEA/SOADSL) only. The default chargeband where not provided is 0. | TRC_CHARGEBAND | Description | | --- | --- | | 0 | 0 hours | | 1 | Up to 2 hours | | 2 | Up to 4 hours | | 3 | Up to 6 hours | | 4 | Unlimited | #### Care Levels The default care level for SOGEA orders is Basic; for FTTP orders is Standard. | CARE_LEVEL | Ecode | Description | | --- | --- | --- | | Basic | E0000154 | Repair within 72 business hours | | Standard | E0000028 | Repair within 48 business hours | | Enhanced | E0000027 | Repair within 24 business hours | | Prompt | E0000029 | Repair within 7 business hours | #### Order updates BB1 provide the following service characteristics in KCIs: - SERVICE_ID - SERVICE_ASSET_ID - CARE_LEVEL_ASSET_ID - STATIC_IP_ASSET_ID - DYNAMIC_IP_ASSET_ID Supplier notes are attached to KCIs as received from BB1 (free text). **Asset Information** Asset information (UUIDs) will be returned as service characteristics in KCIs when you make an order. These must be persisted by the tenant alongside SERVICE_ID as they will be required when requesting future changes to the service. For example, assuming a provide order has been placed at CARE_LEVEL 1, the following assets will have been created: ``` SERVICE_ASSET_ID=548a7b96-4c23-4ce3-b614-6c3f0f357b6d CARE_LEVEL_ASSET_ID=a833c22c-35f3-4b2d-b5f0-e40db4f549bb ``` Later, a modify order must be created to move CARE_LEVEL from 1 to 2. The request must contain additional information including the active line profile, existing service asset id and existing care level asset id to be replaced: ``` LINE_PROFILE=123 action=NONE SERVICE_ASSET_ID=548a7b96-4c23-4ce3-b614-6c3f0f357b6d action=NONE CARE_LEVEL_ASSET_ID=a833c22c-35f3-4b2d-b5f0-e40db4f549bb action=DELETE CARE_LEVEL=1 action=DELETE CARE_LEVEL=2 action=ADD ``` As with the provide order, a KCI will give the new asset id for the chosen care level to again be stored: ``` CARE_LEVEL_ASSET_ID=4da8494c-1a34-41c7-a6b0-fe84795c2c13 ``` For cease orders, the active line profile and existing service asset id must be provided, e.g. ``` LINE_PROFILE=123 action=NONE SERVICE_ASSET_ID=548a7b96-4c23-4ce3-b614-6c3f0f357b6d action=NONE ``` **Unsolicited reappoints** BT Wholesale (or downstream supplier) may on occasion re-appoint the order rather than request the tenant reappoints via an **ACTION_REQUIRED** : **REAPPOINT** KCI. This may be after direct interaction with the end customer. In this scenario, this will come through as an unsolicited reappoint: **INFORMATIONAL** : **REAPPOINTED**. The following fields will be in populated within the KCI order: ```json { "entity": { "appointmentSupplierReference": "123456543", "appointmentTimeslot": { "timeslotStartDateTime": "2022-01-10T08:00:00.000Z", "timeslotEndDateTime": "2022-01-10T13:00:00.000Z" } }, "information": { "type": "REAPPOINTED" } } ``` - appointmentSupplierReference - new appointment reference from the supplier - appointmentTimeslot - new appointment timeslot If this is not suitable then it can be treated as a REAPPOINT. ### Notes: Unsolicited Ceases are not currently sent via the BB1 API. ## Version History ### Tenant API 1.17 / Tenant Updates API 1.14 - Updated to use new textual CARE_LEVEL values (previous number support retained) ### Tenant API 1.13 / Tenant Updates API 1.11 - Added support for multiple supplier codes in single KCI - Enhanced support for BTW features including `SITE_VISIT_REASON` options e.g. Standard vs Premium and Minimum SVR - Added NTE location characteristics for copper-based orders ### Tenant API 1.11 / Tenant Updates API 1.9 - Enhanced service availability response with additional information - Added line profiles in serviceCharacteristics field for service specifications - Populated lineCharacteristics field with speed, availability and lead time data - Added support for installation types (`STANDARD` vs `EXTENDED_STANDARD`) - Added INSTALL_NOTES characteristic for KCI2 Assure addresses ### Tenant API 1.7 / Tenant Updates API 1.5 - Initial connector release for BT Wholesale BB1