# Return available appointment slots for a given service and address.

This endpoint can be called to find what appointments a supplier has available
to install or maintain service(s) at a given address.

An address query parameter must be supplied specifying address ID and type along
with the required service specification as returned by the /service-availability
endpoint.

The next available appointments after the appointmentStartDate will be returned -
a suitable date should be chosen based on installationLeadTime if this was
provided during availability check.

Appointment slots are classified based on day as weekday or saturday/sunday and
by time to day, AM/PM or early morning/evening. Based on the tenant-supplier
agreement, some of these classifications will be considered premium.

This request will be routed to a particular supplier which must be specified.

Endpoint: GET /available-appointments
Version: 1.17
Security: oauth2

## Header parameters:

  - `X-Request-ID` (string, required)
    Unique identifier to identify request and response events across the Fibre Cafe gateway

  - `X-Conversation-ID` (string, required)
    Identifier to track message journey across the Fibre Cafe gateway

## Query parameters:

  - `supplier` (string, required)
    System identifier for a supplier on the Fibre Cafe
    Example: "DUMMY_SUPPLIER"

  - `address` (object, required)
    Address identifier of provided type e.g. UPRN to check for appointment availability
    Example: {"id":"200004033694","type":"UPRN"}

  - `serviceSpecification` (object, required)
    The service to be installed or maintained during this appointment
    Example: {"id":"ftthl2r"}

  - `serviceCharacteristics` (array)
    Characteristics of the service to be maintained during this appointment e.g. SERVICE_ID, CARE_LEVEL

  - `appointmentFromDate` (string)
    Find appointment slots from this date
    Example: "2022-01-05"

  - `standardOnly` (boolean)
    Find appointment slots classified as standard only (exclude premium time slots)

  - `singleDayAppointment` (boolean)
    Find only appointment slots that start/end on the same day

  - `appointmentPurpose` (string, required)
    Purpose of the appointment : PROVIDE, MODIFY, REPAIR
    Example: "PROVIDE"

  - `serviceId` (string)
    Identifier of the existing live service, mandatory if appointmentPurpose is REPAIR
    Example: "SI2345432345345"

## Response 200 fields (application/json):

  - `supplier` (string, required)
    System identifier for a supplier on the Fibre Cafe that is providing this appointment
    Example: "SUPPLIER1"

  - `address` (object, required)
    Address identifier for location including type of identifier.

  - `address.id` (string, required)
    Address identifier of given type
    Example: "A00000031882"

  - `address.type` (string, required)
    Type of address identifier e.g. UPRN, NAD, DistrictCode, ROBT
    Example: "NAD"

  - `address.additionalIdentifiers` (array)
    Additional address identifiers where available/required for subsequent operations

  - `serviceSpecification` (object)
    Details of a service the supplier provides at the selected address.

  - `serviceSpecification.id` (string, required)
    Unique identifier for this service specification
    Example: "ftthl2r"

  - `serviceSpecification.name` (string)
    Name of the service
    Example: "FTTH"

  - `availableTimeslots` (array, required)
    List of available appointment timeslots

  - `availableTimeslots.timeslotStartDateTime` (string, required)
    Start date/time for this timeslot
    Example: "2022-01-10T09:00:00.000Z"

  - `availableTimeslots.timeslotEndDateTime` (string, required)
    End date/time for this timeslot
    Example: "2022-01-10T13:00:00.000Z"

  - `availableTimeslots.classification` (string)
    Timeslot classification:

- WEEKDAY
- WEEKDAY_AM
- WEEKDAY_PM
- WEEKDAY_EARLY
- WEEKDAY_EVENING
- SATURDAY
- SATURDAY_AM
- SATURDAY_PM
- SATURDAY_EARLY
- SATURDAY_EVENING
- SUNDAY
- SUNDAY_AM
- SUNDAY_PM
- SUNDAY_EARLY
- SUNDAY_EVENING
    Example: "SATURDAY_AM"

  - `availableTimeslots.standard` (boolean)
    Timeslot is classified as standard (non-premium)

## Response 400 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]

## Response 401 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]

## Response 422 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]

## Response 500 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]

## Response 502 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]

## Response 504 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]


## Response 403 fields

## Response 503 fields