← Back to Appointments

Introduction

Use these endpoints to create an appointment-request for an order and the starting date you are interested in and to retrieve the slots available from that date.

Request Lifecycle

To create an appointment-request, you must send a POST request to /api/connect/orders/appointment-requests/request with the body of the request containing the order id and the starting date from which available slots will be retrieved. Slots for on or after the provided date will be retrieved.

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.

Make a GET request to this URL to retrieve the results. While the request is in progress, the response’s http status will be 202. This means that the request 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/appointment-requests/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

dateFrom

String

The date from which to request the appointment slots.

Required

orderId

Number

The id of the order.

Required

POST Response

Table 5. POST HTTP Status Codes
Status Code Meaning

201

The request was created successfully

401

Bearer token is missing or invalid

404

You do not have permission to perform this task

422

There are validation errors on the request you made. 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 of the newly created appointment slots request.

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/appointment-requests/requests/{id}
Table 8. GET Request Path Variables

Path Variable

Purpose

id

The id of the appointment-request to poll for a list of slots
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

500

There was an unexpected error processing the request

502

There was an unexpected error with one or more of the upstream services
Table 11. GET Response Body Fields
Path Type Description

[]

Array

List of available appointment slots.

[].slotId

String

The NBN identifier of the appointment slot.

[].slotType

String

For typical AVC connections only AM or PM should be selected. Other options may incur additional charges.Possible values are: AM, PM, AHA, CA

[].startTime

String

The date/time, including UTC offset, appointment start time.

[].endTime

String

The date/time, including UTC offset, appointment end time.

[].timezoneOffset

String

Represents an offset defined in a Timezone.

[].withinTimeWindow

Boolean

Whether the time slot is within Order/Incident SLA or not. Only reliable for Non-'Service Restoration' Demand Types of FTTN, FTTB, and Satellite technologies. For all other appointments, this information is deprecated and should be ignored.

[].leadTime

String

For typical AVC connections only Standard slots should be selected. Other options may incur additional charges.Possible values are: Standard, Accelerated, PriorityAssist, Reduced lead time

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

Successful Appointment request

An appointment request is created by sending a POST request to /api/connect/orders/appointment-requests/request.

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

{
  "dateFrom" : "2025-03-13",
  "orderId" : 13
}

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 of the newly created appointment request entity.

Successful POST Response
HTTP/1.1 201 Created
Location: /api/connect/orders/appointment-requests/requests/301
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

Once you have the URI from the Location header, poll that URI every so often by making a GET request. While the search 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/appointment-requests/requests/2 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer **token**
X-API-VERSION: 7
Host: 360-api.superloop.com
Successful GET Response
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: 418

[ {
  "slotId" : "1",
  "slotType" : "AM",
  "startTime" : "2120-11-11T22:00:00Z",
  "endTime" : "2120-11-12T02:00:00Z",
  "timezoneOffset" : "+10:00",
  "withinTimeWindow" : true,
  "leadTime" : "Standard"
}, {
  "slotId" : "2",
  "slotType" : "PM",
  "startTime" : "2120-11-13T03:00:00Z",
  "endTime" : "2120-11-13T07:00:00Z",
  "timezoneOffset" : "+10:00",
  "withinTimeWindow" : true,
  "leadTime" : "Standard"
} ]

Invalid Appointment request

If the appointment 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 an appointment request without a dateFrom field.

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

{
  "dateFrom" : null,
  "orderId" : 13
}
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: 399

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

Upstream Service Unavailable

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

POST Response with Gateway Error
HTTP/1.1 502 Bad Gateway
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: 249

{
  "httpStatusCode" : 502,
  "type" : "remote.call",
  "code" : "remote.call.error",
  "message" : "There was an unexpected error with one or more of the upstream services",
  "apiSubErrors" : [ ],
  "timestamp" : "2025-03-11T22:23:28.469410851Z"
}