# Reserve a previously returned appointment slot.

This endpoint can be called to reserve an appointment with a supplier to install
or maintain service(s) at a given address.

Details of a previously returned available appointment must be provided to be
reserved according to the supplier reservation policy. Where the reservation
has a TTL (time to live) before being released, the expiry time will be stated.

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

Endpoint: POST /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

## Request fields (application/json):

  - `supplier` (string, required)
    System identifier for a supplier on the Fibre Cafe that is associated with 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, required)
    Details of a service the supplier provides at the selected address.

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

  - `serviceCharacteristics` (array)
    List of service characteristics for the appointment - e.g. CARE_LEVEL

  - `serviceCharacteristics.name` (string, required)
    Name of the service characteristic
    Example: "LINE_PROFILE"

  - `serviceCharacteristics.value` (string, required)
    Value for this characteristic
    Example: "1G1G"

  - `serviceId` (string)
    Identifier of an existing live service, mandatory for REPAIR appointments
    Example: "SI2345432345345"

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

  - `timeslot` (object, required)
    Represents an appointment timeslot with a supplier.

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

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

## Response 201 fields (application/json):

  - `id` (number, required)
    Unique identifier for this appointment
    Example: 345

  - `supplierReference` (string)
    Appointment reference generated by the supplier (for information only)
    Example: "123456543"

  - `expiryDateTime` (string)
    Where an appointment is reserved, this contains the date/time when the reservation will expire.
    Example: "2022-01-01T13:45:00.000Z"

  - `supplier` (string, required)
    System identifier for a supplier on the Fibre Cafe that is associated with 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, required)
    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"

  - `serviceCharacteristics` (array)
    List of service characteristics for the appointment - e.g. CARE_LEVEL

  - `serviceCharacteristics.name` (string, required)
    Name of the service characteristic
    Example: "LINE_PROFILE"

  - `serviceCharacteristics.value` (string, required)
    Value for this characteristic
    Example: "1G1G"

  - `serviceId` (string)
    Identifier of an existing live service, mandatory for REPAIR appointments
    Example: "SI2345432345345"

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

  - `timeslot` (object, required)
    Represents an appointment timeslot with a supplier.

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

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

  - `timeslot.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"

  - `timeslot.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