BT Wholesale B2B Connector Guide

BT Wholesale offers a B2B XML gateway for access to all products and technologies including FTTP, SoGEA and SOADSL. The B2B gateway uses ebXML standards and The Fibre Cafe has a connector to integrate with this gateway.

Authentication & Setup

Authentication with the gateway is CPA/key based. To enable us to set up the connector, the following information is required:

• Reseller DUNS
• Buyer DUNS
• Account number AKA "SellerAssignedAccountID"
• Private key
• CPA XML file from BT
• Cert and key for BBAC (optional)
• BT Wholesale Emulator "Onramp" username/password credentials (for testing only - optional)

Address Lookup

Address lookup uses the BT Wholesale address matching service to return the BT Wholesale/Openreach address identifiers (NAD key and District Code) which are used when sending requests to their gateway. It supports searching by UPRN and postal code/partial address.

The various identifiers are encapsulated into an AddressIdentifier object allowing a single request to contain all identifiers required by different suppliers.

For example:

{
  "identifier": {
    "id": "10091846447",
    "type": "UPRN",
    "additionalIdentifiers": [
      {
        "id": "A15104646284",
        "type": "NAD"
      },
      {
        "id": "LS",
        "type": "DistrictCode"
      }
    ]
  }
}

If a NAD key and District Code are already known, these can be provided directly to the other APIs without needing to perform an address lookup first. The order of identifiers in the AddressIdentifier object is not important.

The address lookup response includes the full address details and qualifier as well as the identifiers. When available, it also includes extra attributes such as whether the address is uninhabited, designated as a "hot site" or classified as a temporary address.

Service Availability

The connector provides comprehensive service availability information including:

• Service specifications and existing line information including ONT information
• Available line profiles for each service type
• Additional line characteristics including minimum/maximum speeds
• Installation information and availability dates

Service Specifications

When returning service specifications (product family/access technology) for an address, the available line profiles are returned in the 'serviceCharacteristics' field:

"serviceSpecifications": [
  {
    "id": "FTTP",
    "name": "WBCFTTP", 
    "serviceCharacteristics": [
      {
        "name": "LINE_PROFILE",
        "values": [
          "1",
          "2"
        ]
      }
    ]
  }
]

FTTP, SOGEA and SOADSL service specifications are supported.

Line Characteristics

The 'lineCharacteristics' field for new or existing lines includes characteristics as defined on the line characteristics page:

"line": {
  ...
  "lineCharacteristics": [
    {
      "name": "MAX_DOWNSTREAM_MBPS", 
      "value": "1000"
    }
  ]
}

This includes minimum and maximum downstream/upstream speeds, availability date and minimum lead time where returned by the BT Wholesale availability checker. Where there is an active pending cease on a line, this is also indicated.

BT Wholesale provide an additional flag for copper-based lines to help indicate availability of SOGEA services:

"existingLines": [
  {
    ...
    "lineCharacteristics": [
      {
        "name": "AVAILABILITY_FLAG",
        "value": "Y"
      }
    ]
  }
]

AVAILABILITY_FLAG is only used for SOGEA. This flag can have the values "Y", "N", "W", "E", "P" 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 SOGEA provide orders
• "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.

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.

Where copper-based lines are returned, the following line characteristics may also be provided to help identify the line:

• PARTIAL_DN - Last digits of a stopped or working line
• NTE FLOOR | NTE ROOM | NTE_POSITION - NTE location attributes

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.

Existing Lines

For FTTP services, existing ONT information includes:

• ONT Reference
• ONT Location (Floor/Room/Position)
• ONT Port Type and Status

For copper lines, existing line information includes:

• Line ID
• NTE Location (Floor/Room/Position)

Stopped date is provided for stopped copper services.

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
• The 'Prove Telecare' SITE VISIT REASON and/or ENSURE_TELECARE engineer task must be used where telecare equipment is in use

Orders

Service Characteristics

The following service characteristics are required when placing orders:

• LINE_PROFILE : See line profiles table below
• RETAILER_ID : Unique identifier for the retailer provided by OFCOM

The following service characteristics are required when placing orders where there are existing services:

• ONT_REFERENCE : Existing ONT reference for FTTP orders using an existing ONT
• LINE_ID : Existing access line identifier for copper orders (SOGEA/SOADSL) with an existing line

These characteristics are optional and will be valid depending on the order type:

• MINIMUM_SPEED : Requested guaranteed minimum speed (also known as realtime) - default is 0
• ECC_CHARGEBAND : Excess construction charges (FTTP) - see charge bands below
• TRC_CHARGEBAND : Time related charges (Copper) - see charge bands below
• CARE_LEVEL : See care levels table below
• SITE_VISIT_REASON : See site visit reasons below
• COMPANY_NAME : Only applicable for Copper (SOGEA/SOADSL) orders
• PROJECT_REFERENCE : Applicable for Copper and FTTP provide journeys with Advanced SITE_VISIT_REASON
• ONT_FLOOR : ONT floor location for FTTP orders
• ONT_ROOM : ONT room location for FTTP orders
• ONT_POSITION : ONT position location for FTTP orders
• NTE_FLOOR : NTE floor location for Copper (SOGEA/SOADSL) orders
• NTE_ROOM : NTE room location for Copper (SOGEA/SOADSL) orders
• NTE_POSITION : NTE position location for Copper (SOGEA/SOADSL) orders
• NAMED_ENGINEER : Named engineer request (Y/N) - provide additional information in NAMED_ENGINEER_NOTES characteristic - non-amendable
• NAMED_ENGINEER_NOTES : Notes to support named engineer request - max 100 characters - non-amendable
• RISK_ASSESSMENT_REQUIRED : SSRAMS (site specific risk assessment and method statement) request - set to 'Y' to request new (chargeable) or 'EXISTING' to use an existing SSRAMS

For SSRAMS requests, the SITE_VISIT_REASON must be 'Premium' or 'Advanced'.

Line Profiles

A LINE_PROFILE characteristic is required for BTW B2B orders. Line profiles map to downstream/upstream speeds as follows:

Excess Construction Charges (ECC)

Charge bands to support extra construction charges - also known as upper cost bands for SOGEA/SOADSL services. The default charge band where not provided is '0' (£0).

Time Related Charges (TRC)

Bands to support time related charges - applies to copper-based orders (SOGEA/SOADSL) only. The default charge band where not provided is '0' (0 hours).

TRCs can be requested by sending an appropriate band with Standard and Premium SITE_VISIT_REASON for SOGEA tech changes, non-tech change modify orders and SOADSL.

'Not Applicable' is always sent for FTTP orders.

Care Levels

The default care level for copper-based orders (SOGEA/SOADSL) is Basic; for FTTP orders is Standard.

Site Visit Reasons

The default site visit reason for appointments and appointed orders is 'Standard'; for unappointed orders is 'No site visit'.

Order Amendments

Amendment and cancellation requests can be made for inflight orders. The following amendments are permitted with BTW B2B:

• Change appointment
• Update contact details
• Update order notes
• Change to ECC_CHARGEBAND or TRC_CHARGEBAND characteristics
• Change to SITE_VISIT_REASON e.g. to 'Premium' or 'Prove Telecare'

Where an order amendment is placed, BTW require additional information in the form of amendment reasons. This includes pre-pone/expedite where the appointment is moved earlier, re-appoint reasons and authorisation for ECC. This is handled automatically where possible by the Fibre Cafe but some intervention may be required depending on the scenario.

Order Updates

Order updates (also known as KCIs or KSUs) are received from BT Wholesale and processed by the connector to update order status and information - the KCIs automatically forwarded to the tenant.

Information and Action Types

KCIs are categorised by then connector and sent with an appropriate action or information type according to the supplier code and KCI content.

The connector supports 'Next Best Action' types 'CONTACTCUSTOMER' and 'CONTACTREAPPOINT' to guide tenants on the best action to take where orders require manual intervention:

• CONTACT_CUSTOMER : Customer contact required to continue order or cancel order
• CONTACT_REAPPOINT : Customer declined, wayleave issue or access/safety issue to be resolved ahead of new appointment

Supplier Codes

The connector returns the codes provided by BT Wholesale in the KCIs. In some scenarios, a single KCI from BTW may be split into multiple KCIs by the Fibre Cafe, but where a single KCI is sent, all supplier codes will be returned in the supplierCodes array:

"supplierCodes": [
  "510", "2001"
]

Service and Line IDs

BTW provides the SERVICE_ID, ONT_REFERENCE and/or LINE_ID as appropriate in a service characteristic before the order completes:

{
  "entity": {
    "serviceOrderItem": {
      "serviceCharacteristics": [
        {
          "name": "SERVICE_ID",
          "value": "BBEU12345678"
        }
      ]
    }
  }
}

Supplier Notes

Supplier notes are attached to KCIs as received from BT Wholesale (free text):

{
  "entity": {
    "supplierNotes": [
      {
        "note": "Lorem ipsum dolor sit amet...",
        "type": "Site Visit Notes", 
        "created": "2024-05-21T17:02:19.652Z"
      }
    ],
    "information": {
      "type": "ADDITIONAL",
      "text": "Adhoc Note to CP",
      "supplierCode": "550"
    }
  }
}

Unsolicited Ceases

Unsolicited ceases are used by BT Wholesale and will be sent as an unsolicited cease KCI. An initial CREATED KCI will be sent once the gateway has received the unsolicited cease, followed by an acknowledged KCI and further KCIs as per the usual order flow. Once the switch is complete, a final completed KCI will be sent.

Example initial KCI for an unsolicited cease:

{
  "id": "12f59a1e-6911-478c-ad5f-12592752990a",
  "updateType": "INFORMATIONAL", 
  "entityType": "UNSOLICITED_CEASE_ORDER",
  "entity": {
    "id": "1234567",
    "orderType": "UNSOLICITED_CEASE",
    "supplier": "BTWHOLESALEB2B",
    "supplierOrderNumber": "1-1124746841144665030934",
    "reason": "CHANGE_OF_CP",
    "serviceId": "BBEU12345678", 
    "status": "RECEIVED_BY_GATEWAY",
    "requestedCeaseDate": "2024-01-01T09:09:33.001Z"
  },
  "information": {
    "type": "CREATED"
  }
}

Unsolicited Reappoints

BTW may occasionally re-appoint orders themselves rather than request the tenant reappoints via an ACTION_REQUIRED : REAPPOINT KCI. This comes through as an unsolicited reappoint: INFORMATIONAL : REAPPOINTED.

The following fields will be populated within the KCI order to show the new appointment details:

{
  "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 BTW
• appointmentTimeslot : New appointment timeslot

If this is not suitable, it can be treated as a REAPPOINT.

Service Testing & Problem Management

The connector supports 'T2R' service testing and problem management for live services. More information on T2R can be found in the 'T2R' section of the Developer Portal.

Service Test

The following parameters are required when requesting a service test:

• serviceId : Identifier of an existing live service
• problemType : The type of problem being experienced with the service
• serviceSpecification : Details of a service the supplier provides at the selected address
• supplier : System identifier for a supplier on the gateway that is associated with this service

Required service characteristics for service testing:

• SERVICE_HAS_WORKED : Indicate if the service has worked at some point
• SERVICE_LAST_WORKED : The date when the service was last working (only required if SERVICE HAS WORKED is true)
• EQUIPMENT_TYPE : The equipment type where the problem is experienced (only required if ProblemType is CPE)

Service Problem

Service problems can be raised after a service test, but not when the service test result is 'GREEN' (to avoid costs for unnecessary engineer visits).

Required parameters for raising a service problem:

• problemType : The type of problem being raised (advised or inferred from service test result)
• problemText : The description of problem being raised as defined by the end user
• serviceId : Identifier of an existing live service
• serviceSpecification : Details of a service the supplier provides at the selected address
• supplier : System identifier for a supplier on the gateway
• serviceTestId : Identifier of a current service test performed against the service
• primaryContact : Contact available at the given address - must be provided
• notes : Notes about the problem which are required by the supplier

Required service characteristics for service problems:

• TRC_CHARGEBAND **: Time related charges - see chargebands
• SERVICE_HAS_WORKED : Indicate if the service has worked at some point
• SERVICE_LAST_WORKED : The date when the service was last working (only if SERVICE HAS WORKED is true)
• END_USER_EQUIPMENT_CHECKED : Confirmation that the end users equipment is connected properly and working
• END_USER_CPE : The type of modem or router of the end user
• CPE_POWER_ON : Confirm that the end users equipment is powered on
• USAGE_CHANGES : Indicate if there has been a recent increase in the end users Application or Data
• PRODUCT_CHANGES : Indicate if there has been any recent product changes or orders for the end user
• 24HR_ACCESS : Confirm there is 24 hour access to the property
• REPEAT_PROBLEM : Confirm if this issue has happened before
• CPE_SYNC_LIGHT_STATUS : What is the state of the modem sync light
• ONT_POWER_ON : Confirm the ONT power light is on

Engineer Appointments

Where an engineer visit is required, appointment timeslots can be listed and reserved using the standard appointing endpoints. The appointmentPurpose field supports REPAIR to ensure the correct type of appointment is booked.

The reserved appointment can be provided on the service problem:

• appointmentReservationId : Identifier of a reserved appointment - provided if an appointment is required

Version History

Tenant API 1.15 / Tenant Updates API 1.13

• Added Prove Telecare value for SITE_VISIT_REASON service characteristic - can be used in conjunction with ENSURE_TELECARE engineer task
• Added support for named engineer and SSRAMS (site specific risk assessment and method statement)

Tenant API 1.13 / Tenant Updates API 1.11

• Added support for multiple supplier codes in single KCI
• Introduced new action types CONTACT_CUSTOMER and CONTACT_REAPPOINT
• Enhanced support for BTW features including SITE_VISIT_REASON options e.g. Standard vs Premium
• Added support for copper-based orders (SOGEA/SOADSL) with upper cost bands for ECC/TRC charges
• Added NTE location characteristics for copper-based orders
• Enhanced order amendment support with additional information requirements

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.10 / Tenant Updates API 1.8

• Added T2R functionality support
• Introduced Service Test capability with required parameters and characteristics
• Added Service Problem management with comprehensive requirements and characteristics

Tenant API 1.7 / Tenant Updates API 1.5

• Initial connector release for BT Wholesale B2B