Skip to main content

Appointment Management

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.

Explore end to end Broadband One order process by API

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

 

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

Back to top