Getting started
For Broadband One, when a Managed Install is required, you'll need to find and reserve an appointment.
The reference for any reserved appointment needs to be included in the submitted order it relates to.
To see how this API forms part of the wider Broadband One order process, click the diagram below.
When is a Managed Install required?
Whenever an Openreach engineer is needed to perform installation tasks at an end user's premises.
This can be for provide type orders but also modify orders involving a change in network technology or when an end user wishes for a network termination (NTE/ONT) to be moved within the premises.
Finding and Reserving Appointments
Available appointment slots are kept in appointment books which can be searched.
Appointment availability varies with location. One can specify the location required for an appointment using one of either an address key or line identifier for the premises where the installation is required. The line identifier can be an Openreach known fixed line telephone number for the premises or the access line id for a working line serving the premises.
Appointment books are divided by appointment type, site visit reason, and access network technology.
The usual appointment type is Standard and availability reflects the standard lead times for provision of the access technology required. Expedited appointments relate to where a reduced lead time has been asked for by the end user. the Supplier Failed appointment type is for reappointing an order where Openreach have failed to meet the original appointment.
Access technology not only covers SOADSL, SOGEA and FTTP but also whether the SOGEA install is using a new of existing line. There is also a separate access technology for FTTP standalone ONT Shift modify orders.
Site visit reason (Standard, Premium and Advanced) reflects the amount of effort required to carry out the installation task. Standard is the base installation including installing the network termination, connecting and powering up a modem and connecting one device to prove that the service is working. Premium and Advanced covers additional work including additional in building cabling.
Based on the requirements, a number of appointment slots (am and pm) are offered, starting from the earliest appointment available date or the "validFrom" date whichever is later.
To reserve an appointment the same requirements are specified again (this time with the required appointment slot) and , if valid, an appointment reference is returned which can be included in the order.
The tutorial below covers as an example finding and making an appointment for an FTTP standard installation.
Summary of Appointment Attributes
| Attribute | Values | Notes |
|---|---|---|
| appointmentType |
'Standard', 'Expedited', 'Supplier Failed' |
Expedited only applies to SoGEA and FTTP appointments. SoADSL only supports Standard appointments. |
| siteVisitReason |
'Standard', 'Premium', 'Advanced' |
SoADSL only supports Standard and Premium. |
|
value for characteristic name "AccessTechnology" |
'FTTP', 'FTTP Shift ONT', 'SOADSL', 'SOGEA New Line', 'SOGEA Existing Line' |
|
|
value for characteristic name "AccessLineId" |
Alternative to address key. Access line id for working line at the premises. |
|
|
value for characteristic name "DirectoryNumber" |
Alternative to address key. Openreach fixed line phone number for working line at the premises. |
What you'll learn
- Find appointment
-
Reserve appointment
Find an appointment
Request Method & URI
POST /appointmentManagement/v4/searchTimeSlot
Request Entity - Body
To return a list of suitable appointments, we need to know:
- When you want one
- The access technology required
- What's expected from the appointment.
| Key | Example value | What you need to know |
|---|---|---|
| value | FTTP | Access technology. Other values are SOGEA New Line, SOGEA Existing Line, and SOADSL, |
| place.id | A15104999999 | Openreach Gold NAD key. |
| startDateTime | 2022-11-29T08:00:00Z | ISO format. Date and time from which you want to search for an appointment. |
| appointmentType | Standard | Other values are Expedited, and Supplier Failed (for rebooking appointment in case of missed appointment). |
| siteVisitReason | Standard | Standard is the default value for all access technologies. Alternatives are Premium and Advanced. |
Appointment date and time
The startDateTime example value shown above (2022-11-29T08:00:00Z) is an ISO-format string that comprises:
- The date, in YYYY-MM-DD format
- T
- The time, as HH:MM:SS
- A single-character suffix; either:
- Z, if during GMT (starts the last Sunday of October at 0200 BST, ends last Sunday of March at 0100 GMT), or
- +01:00, if during BST (starting the last Sunday of March at 0100 GMT, ends last Sunday of October at 0200 BST)
If the example appointment during BST, the start time would be shown as:
T08:00:00+01:00
Payload
{ "relatedEntity": [
{ "appointmentType": "Standard",
"siteVisitReason": "Standard",
"product": {
"productSpecification": {"id": "BB1"},
"characteristic": [
{ "name": "AccessTechnology",
"value": "FTTP" } ],
"place": [
{ "id": "A15104999999",
"role": "InstallationAddress",
"@referredType": "OpenreachAddress"} ] },
"id": "1",
"role": "OrderInformation",
"@referredType": "BTProductAppointmentSpecification",
"@type": "BTProductAppointmentSpecification",
"@baseType": "RelatedEntity" } ],
"requestedTimeSlot": [
{"validFor": {"startDateTime": "2022-11-22T09:00:00Z"} } ] }Response Entity-Body
You're looking for the start and end date and time for the suitable appointment from a list of options.
Here's the appointment we'll be selecting from the response below:
| Property | Value (example) |
|---|---|
| startDateTime | 2022-11-29T08:00:00Z |
| endDateTime | 2022-11-29T13:00:00Z |
Payload
{ "id": "21147d79-577b-488a-af57-f80ea5dfb876",
"status": "done",
"searchDate": "2022-11-09T07:06:39Z",
"relatedEntity": [
{ "appointmentType": "Standard",
"siteVisitReason": "Standard",
"product": {
"productSpecification": {"id": "BB1"},
"characteristic": [
{ "name": "AccessTechnology",
"value": "FTTP"} ],
"place": [
{ "id": "A15104646632",
"role": "InstallationAddress",
"@referredType": "OpenreachAddress"} ] },
"id": "1",
"role": "OrderInformation",
"@referredType": "BTProductAppointmentSpecification",
"@type": "BTProductAppointmentSpecification",
"@baseType": "RelatedEntity"} ],
"requestedTimeSlot": [
{ "validFor": {"startDateTime": "2022-11-22T09:00:00Z"} } ],
"availableTimeSlot": [
{ "slot": "AM",
"validFor": {
"startDateTime": "2022-11-29T08:00:00Z",
"endDateTime": "2022-11-29T13:00:00Z"} },
{ "slot": "AM",
"validFor": {
"startDateTime": "2022-12-01T08:00:00Z",
"endDateTime": "2022-12-01T13:00:00Z"} },
{ "slot": "PM",
"validFor": {
"startDateTime": "2022-12-01T13:00:00Z",
"endDateTime": "2022-12-01T18:00:00Z"} }, ] }This is a heavily truncated response payload.
What start and end times mean
While it’s perhaps not critical to your work as developer, it’s helpful to know the time range between startDateTime and endDateTime is when the Managed Install engineer should begin their work. It gives no indication when the work will be finished, or service available.
You will be updated on engineering progress and service installation through order updates (KSUs) to your chosen endpoint.
Occasionally, a further engineering visit may be required. You will be notified by KSU if this is the case, at which point you can find, reserve, and book it following the same process.
Reserve appointment
Now you've found a suitable slot, you need to reserve it.
A successful request will return an appointment ID which should be included when you place the Broadband One order.
On receiving this appointment ID, you have 24 hours to confirm the visit.
Request Method & URI
POST /appointmentManagement/v4/appointment
Request Entity-Body
You'll create this payload with several values used to find an appointment.
In addition, you need to include the start and end date and time of the chosen appointment.
| Key | Example value |
|---|---|
| value | FTTP |
| place.id | A15104646632 |
| startDateTime | 2022-11-29T08:00:00Z |
| endDateTime | 2022-11-29T13:00:00Z |
| appointmentType | Standard |
| siteVisitReason | Standard |
Payload
{
"relatedEntity": [
{
"appointmentType": "Standard",
"siteVisitReason": "Standard",
"product": {
"productSpecification": {
"id": "BB1"
},
"characteristic": [
{
"name": "AccessTechnology",
"value": "FTTP"
}
],
"place": [
{
"id": "A15104646632",
"role": "InstallationAddress",
"@referredType": "OpenreachAddress"
}
]
},
"id": "1",
"role": "OrderInformation",
"@referredType": "BTProductAppointmentSpecification",
"@type": "BTProductAppointmentSpecification",
"@baseType": "RelatedEntity"
}
],
"validFor": {
"startDateTime": "2022-11-29T08:00:00Z",
"endDateTime": "2022-11-29T13:00:00Z"
}
}Response Entity-Body
On receiving this payload you need to store two values confirming the appointment has been reserved. This table includes their associated properties when placing the order.
| Property | Value (example | Place order API property |
|---|---|---|
| id | A42D0BDFR | BESAppointmentId |
| startDateTime | 2022-11-29T08:00:00Z | appointment.appointmentStart |
Payload
{ "id": "A42D0BDFR",
"status": "initialized",
"creationDate": "2022-11-05T19:15:14Z",
"relatedEntity": [
{ "appointmentType": "Standard",
"siteVisitReason": "Standard",
"product": {
"productSpecification": {"id": "BB1"},
"characteristic": [
{ "name": "AccessTechnology",
"value": "FTTP"} ],
"place": [
{ "id": "A15104999999",
"role": "InstallationAddress",
"@referredType": "OpenreachAddress"} ] },
"id": "1",
"role": "OrderInformation",
"@referredType": "BTProductAppointmentSpecification",
"@type": "BTProductAppointmentSpecification",
"@baseType": "RelatedEntity"} ],
"validFor": {
"startDateTime": "2022-11-29T08:00:00Z",
"endDateTime": "2022-11-29T13:00:00Z"} }On receiving a 200 status code, you can proceed to placing the Broadband one order within 24 hours to confirm this appointment.
Other Broadband One tutorials
Additional support
- Broadband One Product Handbook (BT Wholesale login required)
- Reference documentation
- Product catalogue
- Knowledge centre