Skip to content
Tenants
/
/
Openreach
Last updated

Openreach B2B Connector Guide

Openreach offers a B2B XML gateway for access to all products and technologies including FTTP and SOGEA. 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:

  • Buyer DUNS
  • CPA XML file from Openreach (if applicable)

Address Lookup

Address lookup uses the Openreach address matching service to return the BT/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.

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": "FTTP", 
    "serviceCharacteristics": [
      {
        "name": "LINE_PROFILE",
        "values": [
          "1",
          "2"
        ]
      }
    ]
  }
]

Only FTTP is supported in the initial release - SOGEA and SOTAP support is planned for a future release.

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 (where supplied), availability date and minimum lead time where returned.

Installation Types

Openreach 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

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

Line Profiles

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

LINE_PROFILEDownstream MbpsUpstream MbpsAccess Technology
10110015FTTP
10210030FTTP
10311015FTTP
10411520FTTP
10516030FTTP
10622020FTTP
10722030FTTP
10833020FTTP
10933030FTTP
11033050FTTP
111500165FTTP
11255075FTTP
1131000115FTTP
1141000220FTTP
11510001000FTTP
1161200120FTTP
1171800120FTTP
1182500250FTTP
1192500500FTTP
12025002500FTTP
1213300330FTTP
1223300660FTTP
12333003300FTTP

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).

ECC_CHARGEBANDFTTPSOGEASOADSL
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
6n/a£3000 - £99999£5000
7n/an/a£10000
8n/an/a£15000

Care Levels

The default care level for FTTP orders is Level 2.

CARE_LEVELNotes
1Clear by 23:59 day after next, Mon to Fri (excl bank holidays) [copper only]
2Clear by 23:59 next day, Mon to Sat (excl bank holidays) [default]
3Report 13.00, clear by 23:59 same day. Report after 13:00 clear by 12:59 next day
4Clear within 6 hours

Site Visit Reasons

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

SITE_VISIT_REASONNotes
No site visitDefault for non-appointed orders
StandardDefault for appointed orders / reserved appointments
Premium
Advanced

Order Amendments

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

  • 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, Openreach 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 Openreach 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 'CONTACT_CUSTOMER' and 'CONTACT_REAPPOINT' 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 Openreach in the KCIs. In some scenarios, a single KCI from Openreach 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

Openreach provides the SERVICE_ID and ONT_REFERENCE 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 Openreach (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 Openreach 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": "OPENREACH",
    "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

Openreach 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 Openreach
  • appointmentTimeslot: New appointment timeslot

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

Version History

Tenant API 1.15 / Tenant Updates API 1.13

  • Initial connector release for Openreach
Previous page
Next page