# Reserve an appointment slot.

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.

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

  - `Tenant` (string, required)
    The tenant that has placed the request on the Fibre Cafe
    Example: "TENANT1"

## Request fields (application/json):

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

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

  - `address.id` (string, required)
    Address identifier of provided type e.g. UPRN
    Example: "200004033694"

  - `address.type` (string, required)
    Type of addressId provided e.g. UPRN
    Example: "UPRN"

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

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

  - `purpose` (string)
    Purpose of the appointment : PROVIDE, REPAIR, MODIFY
    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):

  - `supplierReference` (string)
    Unique reference generated by the supplier for this appointment
    Example: "A234"

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

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

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

  - `address.id` (string, required)
    Address identifier of provided type e.g. UPRN
    Example: "200004033694"

  - `address.type` (string, required)
    Type of addressId provided e.g. UPRN
    Example: "UPRN"

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

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

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

  - `purpose` (string)
    Purpose of the appointment : PROVIDE, REPAIR, MODIFY
    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
    Enum: "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"

  - `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: "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_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: "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_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: "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_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: "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_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