← Back to Appointments

Introduction

Use these endpoints to cancel a booked appointment.

Request Lifecycle

Cancelling a booked appointment is a two step process as follows:

  1. Create an appointment-cancellation-request resource, by sending a POST request to /api/connect/orders/appointment-cancellations/request with the body of the request containing the appointment id of the appointment you would like to try and cancel. 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.

  2. Make a GET request to the URL returned in 1. to retrieve the outcome of the request. 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. If the request was successful an appointment-cancellation resource will be returned. If the request failed a 422 will be returned with the body containing details on why it failed in the standard error format.

  3. If the request is successful and you are subscribed to the appointment.cancelled event then an AppointmentCancelled webhook notification will be sent.

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 Request

Table 2. POST Request

Verb

POST

URI

/api/connect/orders/appointment-cancellations/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

appointmentId

Number

The id of the appointment to cancel

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 from where the outcome of the request can be obtained. Poll this URL until the request is complete

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

Path Variable

Purpose

id

The id of the appointment-cancellation-request resource. This was generated by 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 appointment-cancellation resource

202

The request is in progress

400

The request was bad. Check the response body to see what the issue(s) are

401

Bearer token is missing or invalid

404

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

422

The appointment-cancellation resource failed to be created. Check the response body to see why

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

id

Number

The Connect identifier of the appointment-cancellation resource

appointmentId

Number

The Connect identifier of the appointment resource

nbnAppointmentId

String

The nbn identifier of the appointment

cancelledOn

String

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

requestedOn

String

The date/time, including UTC offset, when the request to cancel the appointment was made

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

Successful Request

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

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

{
  "appointmentId" : 3
}

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 appointment-cancellation resource.

Successful POST Response
HTTP/1.1 201 Created
Location: /api/connect/orders/appointment-cancellations/requests/4
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 cancelling the booked appointment is in progress, the GET request’s response will have a http status of 202. Keep polling the URL until it finishes, once the request is completed successfully the GET request’s response will have a http status of 200.

Note
 Please keep the polling to a sensible rate.
GET Request
GET /api/connect/orders/appointment-cancellations/requests/4 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 appointment cancellation 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
Successful GET Response appointment cancelled
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: 163

{
  "id" : 4,
  "appointmentId" : 3,
  "nbnAppointmentId" : "APT790002088783",
  "cancelledOn" : "2025-03-11T22:23:15Z",
  "requestedOn" : "2025-03-11T22:23:15Z"
}

Invalid Request

If the 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.

Appointment not booked
POST Response with 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: 418

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "validation",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.appointment.not.booked",
    "message" : "Appointment with id 1 cannot be cancelled as it is not booked",
    "object" : "Appointment",
    "field" : "status",
    "rejectedValue" : "complete"
  } ],
  "timestamp" : "2025-03-11T22:23:23.508359797Z"
}
Appointment has a cancellation already in progress
POST Response with 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: 446

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "validation",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.appointment-cancellation.in.progress",
    "message" : "Appointment with id 2 already has a cancellation in progress",
    "object" : "AppointmentCancellation",
    "field" : "status",
    "rejectedValue" : "IN_PROGRESS"
  } ],
  "timestamp" : "2025-03-11T22:23:13.689525441Z"
}
Appointment has a cancellation pending
POST Response with 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: 452

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "validation",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.appointment.not.cancellable",
    "message" : "Appointment is already pending cancellation.",
    "object" : "Appointment",
    "field" : "nbnInternalAppointmentId",
    "rejectedValue" : "20004a91-cc6c-47ee-81d2-494c7e36b252"
  } ],
  "timestamp" : "2025-03-11T22:23:17.013085499Z"
}
Appointment past point of no return
POST Response with 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: 447

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "validation",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.appointment.not.cancellable",
    "message" : "Appointment is past point of no return.",
    "object" : "Appointment",
    "field" : "nbnInternalAppointmentId",
    "rejectedValue" : "20004a91-cc6c-47ee-81d2-494c7e36b252"
  } ],
  "timestamp" : "2025-03-11T22:23:18.273449092Z"
}
Appointment in an invalid state
POST Response with 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: 450

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "validation",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.appointment.not.cancellable",
    "message" : "Appointment not in a valid state to cancel.",
    "object" : "Appointment",
    "field" : "nbnInternalAppointmentId",
    "rejectedValue" : "20004a91-cc6c-47ee-81d2-494c7e36b252"
  } ],
  "timestamp" : "2025-03-11T22:23:20.68985054Z"
}
Bad Request
GET Request bad request
GET /api/connect/orders/appointment-cancellations/requests/AAA HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer **token**
X-API-VERSION: 7
Host: 360-api.superloop.com
GET Response bad request
HTTP/1.1 400 Bad Request
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: 363

{
  "httpStatusCode" : 400,
  "type" : "client.validation",
  "code" : "method.argument.type.mismatch",
  "message" : "Failed to convert value of type 'java.lang.String' to required type 'java.lang.Integer'; nested exception is java.lang.NumberFormatException: For input string: \"AAA\"",
  "apiSubErrors" : [ ],
  "timestamp" : "2025-03-11T22:23:21.808806355Z"
}

Upstream Service Unavailable

If one of the services that Connect API uses for cancelling a booked appointment is down or unreachable, Connect API will return a http status of 502.

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:19.483688276Z"
}

Resource failed to be created

If the appointment-cancellation resource failed to be created, a http status of 422 is returned and the body of the response will list the reason why

GET Response resource failed to be created
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: 632

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "validation",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.appointment-cancellation.failed",
    "message" : "InvalidAppointmentException: Appointment ID : APT000000000001 is past the cancellation Point of No Return (cPoNR). \"standard_description\":\"InvalidAppointmentException: Appointment ID : APT000000000001 is past the cancellation Point of No Return (cPoNR).",
    "object" : "AppointmentCancellation",
    "field" : "status",
    "rejectedValue" : "FAILED"
  } ],
  "timestamp" : "2025-03-11T22:23:24.958155154Z"
}