← Back to Appointments

Introduction

Booking an appointment is the process of trying to turn an appointment-request into a booked appointment with the nbn. To do this you need to have created an appointment-request and obtained the available slots. To book the appointment you will first make a request to book the appointment and then poll for the outcome of the request.

Request Lifecycle

To book the appointment, you must send a POST request to /api/connect/orders/appointments/request with the body of the request containing the appointment-request id and the slot id.

The response’s http status will be 201 with a blank response body. There will be a Location response header with a URL. This URL is where the request outcome can be obtained. It will either return the booked appointment, return an error if the appointment could not be booked or indicate if the appointment is still in the process of being booked.

Make a GET request to this URL to retrieve the results of booking the appointment. While the appointment is in the progress of being booked, the response’s http status will be 202. This means that the booking has not finished yet, but will in a moment.

Request Specifications

Table 1. API Versions
Version Header Changes

1 (Deprecated)

X-API-VERSION=1

Initial Version

2 (Deprecated)

X-API-VERSION=2

No Change

3

X-API-VERSION=3

No Change

4

X-API-VERSION=4

No Change

5

X-API-VERSION=5

No Change

6

X-API-VERSION=6

No Change

7

X-API-VERSION=7

No Change

API Version 1, 2, 3, 4, 5, 6 and 7 - POST

POST Request

Table 2. POST Request

Verb

POST

URI

/api/connect/orders/appointments/request
Table 3. POST HTTP Request Headers
Name Description

Authorization

The OAuth bearer access token

X-API-VERSION

The version of the endpoint you are accessing
Table 4. POST Request Body Fields
Path Type Description Required

appointmentRequestId

Number

The id of the appointment-request to book

Required

slotId

String

The id of the slot you want to book

Required

POST Response

Table 5. POST HTTP Status Codes
Status Code Meaning

201

The request was created successfully

401

Bearer Token missing or invalid

404

You are not authorised

422

There are validation errors on the request. Check the response body to see what fields had issues

500

There was an unexpected error processing the request

502

There was an unexpected error with one or more of the upstream services
Table 6. POST HTTP Response Headers
Name Description

Location

The URL from where the outcome of the request can be obtained. Poll this URL until the request is complete.

API Version 1, 2, 3, 4, 5, 6 and 7 - GET

GET Request

Note
 The URI will be given to you in the Location header of the POST request.
Table 7. GET Request

Verb

GET

URI

/api/connect/orders/appointments/requests/{id}
Table 8. GET Request Path Variables

Path Variable

Purpose

id

The id of the appointment-request you booked. This is the appointmentRequestId used in the POST request
Table 9. GET HTTP Request Headers
Name Description

Authorization

The OAuth bearer access token

X-API-VERSION

The version of the endpoint you are accessing

GET Response

Table 10. GET HTTP Status Codes
Status Code Meaning

200

The request is complete. The body contains the results

202

The request is in progress

401

Bearer token is missing or invalid

404

You are not authorised or The id (of the appointment-request) provided does not exist

422

The appointment failed to be booked. Check the response body to see why

500

There was an unexpected error processing the request
Table 11. GET Response Body Fields
Path Type Description

id

Number

The Connect identifier of the appointment resource.

nbnAppointmentId

String

The NBN identifier of the appointment.

slotType

String

The type of confirmed appointment slot. AM/PM.

startTime

String

The date/time, including UTC offset, appointment start time will be visible only when appointment has been confirmed.

endTime

String

The date/time, including UTC offset, appointment end time, will be visible only when appointment has been confirmed.

timezoneOffset

String

Represents an offset defined in a Timezone.

priorityAssist

Boolean

Indicates whether the appointment is priority assisted or not.

eSla

String

The level of restoration SLA that the service will have. Currently, only Standard is available.

demandType

String

The type of installation the appointment slot is provided for.

contact

Object

The contact details of the appointment.

contact.name

String

The name of the contact.

contact.type

String

The type of the contact.

contact.phone

String

The number of the contact.

contact.notes

String

Additional information. If any.

bookedOn

String

The date/time, including UTC offset, when nbn validated the appointment.

cancellationRequests

Array

List of cancellation requests for the appointment. Will be empty when first booked.

API Version 1, 2, 3, 4, 5, 6 and 7 - Examples

Appointment Booked

A request to book an appointment is created by sending a booking request JSON object as a POST request to /api/connect/orders/appointments/request.

POST Request
POST /api/connect/orders/appointments/request HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer **token**
X-API-VERSION: 7
Content-Length: 52
Host: 360-api.superloop.com

{
  "appointmentRequestId" : 100,
  "slotId" : "1"
}

If all required fields were given, then the response to the request will have:

  1. a http status of 201

  2. a Location header with the URI where the request outcome can be obtained

Successful POST Response
HTTP/1.1 201 Created
Location: /api/connect/orders/appointments/requests/100
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

The booking of the appointment is not instantaneous. It takes a small amount of time for Connect API to book the appointment with the nbn. This is why you have to send a POST request to request the booking of the appointment.

Once you have the URI from the Location header, poll that URI every so often by making a GET request. While the booking is in progress, the GET request’s response will have a http status of 202. Keep polling the URL until it finishes.

Note
 Please keep the polling to a sensible rate.
GET Request
GET /api/connect/orders/appointments/requests/100 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer **token**
X-API-VERSION: 7
Host: 360-api.superloop.com
GET Response when booking is still in progress
HTTP/1.1 202 Accepted
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

When Connect API completes the booking, the next GET request will result in a response with a http status of 200. The response body’s will contain details of the booked appointment.

GET Response when booking is complete
HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 495

{
  "id" : 1,
  "nbnAppointmentId" : "APT000000000001",
  "slotType" : "AM",
  "startTime" : "2020-06-16T21:00:00Z",
  "endTime" : "2020-06-17T04:00:00Z",
  "timezoneOffset" : "+10:00",
  "priorityAssist" : false,
  "eSla" : "Standard",
  "demandType" : "Non EU Jumper Only",
  "contact" : {
    "name" : "Alice Smith",
    "type" : "Primary Contact",
    "phone" : "0123456789",
    "notes" : "This is an appointment"
  },
  "bookedOn" : "2020-06-10T06:46:06Z",
  "cancellationRequests" : [ ]
}

Invalid booking request

If the booking request is invalid for any reason, a http status of 422 is returned and the body of the response will list the problems with the request.

This example is of submitting a booking request without an id field.

POST Request
POST /api/connect/orders/appointments/request HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer **token**
X-API-VERSION: 7
Content-Length: 53
Host: 360-api.superloop.com

{
  "appointmentRequestId" : 100,
  "slotId" : null
}
POST Response with request validation errors
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 398

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "method.argument.not.valid",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.not.blank",
    "message" : "must not be blank",
    "object" : "connectNbnBookAppointmentRequestCommand",
    "field" : "slotId",
    "rejectedValue" : null
  } ],
  "timestamp" : "2025-03-11T22:23:29.864678262Z"
}

Booking of Appointment failed

If the booking failed for any reason, a http status of 422 is returned and the body of the response will list the reason(s) why.

GET Request
GET /api/connect/orders/appointments/requests/200 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer **token**
X-API-VERSION: 7
Host: 360-api.superloop.com
GET Response with reason why booking failed
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 431

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "validation",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.appointment-request.in-error",
    "message" : "The Appointment Request has errored due to No Slots Available",
    "object" : "AppointmentRequest",
    "field" : "status",
    "rejectedValue" : "IN_ERROR"
  } ],
  "timestamp" : "2025-03-11T22:23:31.019438873Z"
}

Upstream Service Unavailable

If one of the services that Connect API uses for booking the appointment is down or unreachable, Connect API will send a 502 status.

POST Response with Gateway Error
HTTP/1.1 502 Bad Gateway
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY