Getting started
For Broadband One, when a Managed Install is required, you'll need to find and reserve an appointment.
To see how this API forms part of the wider Broadband One order process, click the diagram below.
When is a Managed Install required?
FTTP
When a new ONT is required or an existing ONT needs to be replaced or moved.
SOGEA/FTTC/ADSL
- New line is required
- Existing NTE is damaged or needs to be moved
If required, the Managed Install can include the connection of a modem and additional device to show Broadband One is working.
What you'll learn
- Find appointment
- Reserve appointment
See the full Broadband One order process by clicking the diagram below.
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, FTTC, and ADSL. |
| 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. Premium is for FTTP and SOGEA. Find out the service associated with each value by consulting the Broadband One handbook. |
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