Reserve an appointment slot.

post/appointments

This endpoint is called to reserve an appointment with a supplier to install service(s) at a given address.

This endpoint will be supplied a previously returned available appointment slot to be reserved according to the supplier reservation policy. Where the reservation has a TTL (time to live) before being released, the expiry time should be returned.

The returned appointment ID will be sent as part of the order at which point it should be considered confirmed.

SecuritybearerAuth
Request
header Parameters
X-Request-ID
required
string

Unique identifier to identify request and response events across the gateway

X-Conversation-ID
required
string

Identifier to track message journey across the gateway

Tenant
required
string

The tenant that has placed the request on the gateway

Example: TENANT1
Request Body schema: application/json
id
required
number >= 1

Unique identifier for this appointment

required
object (AddressIdentifier)

Address identifier for location including type of identifier.

required
object (ServiceSpecification)

Details of a service the supplier provides at the selected address.

purpose
string (AppointmentPurpose)

Purpose of the appointment : PROVIDE, REPAIR, MODIFY

required
object (Timeslot)

Represents an appointment timeslot with a supplier.

Responses
201

Operation successful - appointment was reserved. Returned ID will be used when placing order

400

Bad request - supplied request was malformed or missing mandatory parameters

401

Unauthorised access

403

The client is not permitted to access this resource.

422

Unprocessable entity - invalid data was provided

500

Invalid or failed response from the supplier

503

Supplier API is temporarily unavailable

Request samples
application/json
{
  • "id": 234,
  • "address": {
    • "id": "200004033694",
    • "type": "UPRN"
    },
  • "serviceSpecification": {
    • "id": "ftthl2r"
    },
  • "purpose": "PROVIDE",
  • "timeslot": {
    • "timeslotStartDateTime": "2022-01-10T09:00:00.000Z",
    • "timeslotEndDateTime": "2022-01-10T13:00:00.000Z"
    }
}
Response samples
application/json
{
  • "supplierReference": "A234",
  • "expiryDateTime": "2022-01-01T13:45:00.000Z",
  • "id": 234,
  • "address": {
    • "id": "200004033694",
    • "type": "UPRN"
    },
  • "serviceSpecification": {
    • "id": "ftthl2r",
    • "name": "FTTH"
    },
  • "purpose": "PROVIDE",
  • "timeslot": {
    • "timeslotStartDateTime": "2022-01-10T09:00:00.000Z",
    • "timeslotEndDateTime": "2022-01-10T13:00:00.000Z",
    • "classification": "SATURDAY_AM",
    • "standard": true
    }
}