# Reserve Appointment

In order to reserve an appointment, the buyer should provide the UPRN, product and the appointment slot that they desire to the seller

Endpoint: POST /reserveAppointment
Version: 2.31
Security: Certificate

## Request fields (application/xml):

  - `message` (object, required)
    The meta-data of the request. It includes information regarding the message UUID, transaction ID and the sent timestamp

  - `message.messageId` (string, required)
    A unique ID to identify the message
    Example: b68b2cf4-475e-11e1-a92e-fb2ff6467c99

  - `message.correlationId` (string, required)
    A Correlation ID, also known as a Transit ID, is a unique identifier value that is attached to requests and messages that allow reference to a particular transaction or event chain
    Example: bac72cfa-475e-11e1-a92e-fb2ff6467c99

  - `message.sentAt` (string, required)
    The timestamp when the message has been sent
    Example: 2012-01-20T18:30:43Z

  - `buyer` (object, required)
    The Service Provider who consumes the service is the buyer

  - `buyer.buyerIdentifier` (string, required)
    Unique identifier of the buyer
    Example: SPDEV1

  - `buyer.cfh:resellerId` (string)
    Unique identifier of the reseller. Sourced from the Ofcom Reseller Identification List
    Example: BAQ

  - `seller` (object, required)
    the Active Network Operator who provides the service is the seller

  - `seller.sellerIdentifier` (string, required)
    Unique identifier of the seller
    Example: CITYFIBRE

  - `appointmentSlot` (object, required)
    Represents the appointment slot details. Simple orders always carry the single-day `appointmentDate`, `appointmentStartTime` and `appointmentEndTime`. Complex installation orders (`orderSurvey`/`orderExternal`/`orderInternal`) additionally carry `cfh:startDateTime`/`cfh:endDateTime`; for these the single-day triple is present only when the slot starts and ends on the same day and is omitted for multi-day slots (possible for `orderExternal`).

  - `appointmentSlot.appointmentDate` (string)
    Date of the appointment
    Example: 2012-01-20

  - `appointmentSlot.appointmentStartTime` (string)
    Appointment start time
    Example: 08:00

  - `appointmentSlot.appointmentEndTime` (string)
    Appointment end time
    Example: 08:00

  - `appointmentSlot.cfh:startDateTime` (string)
    Start of the appointment as a full ISO 8601 UTC date-time. Present on complex installation appointments (`orderSurvey`, `orderExternal`, `orderInternal`). Together with `cfh:endDateTime` it is the authoritative slot boundary, and is the only representation when an appointment spans multiple days (possible for the `orderExternal` build-to-wall stage).
    Example: 2023-05-01T08:00:00Z

  - `appointmentSlot.cfh:endDateTime` (string)
    End of the appointment as a full ISO 8601 UTC date-time. Present on complex installation appointments (`orderSurvey`, `orderExternal`, `orderInternal`). For a multi-day appointment (possible for the `orderExternal` build-to-wall stage) its date differs from `cfh:startDateTime`.
    Example: 2023-05-01T13:00:00Z

  - `appointmentType` (any, required)
    Identifies the type of appointment being queried, reserved or amended. Complex installation orders progress through the survey, build-to-wall and standard-install appointment types in turn.

  - `appointmentType.order` (null)
    Standard install appointment for a simple (non-complex) order.

  - `appointmentType.fault` (null)

  - `appointmentType.orderSurvey` (null)
    Books the physical survey appointment for a complex installation order. Used during the Physical Survey stage.

  - `appointmentType.orderExternal` (null)
    Books the Build to Wall appointment for a complex installation order. Always appointed.

  - `appointmentType.orderInternal` (null)
    Books the Standard Install appointment for a complex installation order. Always appointed.

  - `cfh:productName` (string, required)
    This is the product name
    Example: ftthl2r

  - `cfh:addressKey` (string, required)
    The address key (UPRN)
    Example: 123456789012

  - `cfh:ispMigration` (string)
    Flag for ISP Migration
    Example: true

  - `cfh:reappointment` (string)
    Indicates whether the appointment is reappointing a previous appointment
    Example: true

  - `cfh:projectReference` (string)
    Example: CST1234567

## Response 200 fields (application/xml):

  - `message` (object, required)
    The meta-data of the request. It includes information regarding the message UUID, transaction ID and the sent timestamp

  - `message.messageId` (string, required)
    A unique ID to identify the message
    Example: b68b2cf4-475e-11e1-a92e-fb2ff6467c99

  - `message.correlationId` (string, required)
    A Correlation ID, also known as a Transit ID, is a unique identifier value that is attached to requests and messages that allow reference to a particular transaction or event chain
    Example: bac72cfa-475e-11e1-a92e-fb2ff6467c99

  - `message.sentAt` (string, required)
    The timestamp when the message has been sent
    Example: 2012-01-20T18:30:43Z

  - `buyer` (object, required)
    The Service Provider who consumes the service is the buyer

  - `buyer.buyerIdentifier` (string, required)
    Unique identifier of the buyer
    Example: SPDEV1

  - `buyer.cfh:resellerId` (string)
    Unique identifier of the reseller. Sourced from the Ofcom Reseller Identification List
    Example: BAQ

  - `seller` (object, required)
    the Active Network Operator who provides the service is the seller

  - `seller.sellerIdentifier` (string, required)
    Unique identifier of the seller
    Example: CITYFIBRE

  - `reserveAppointmentAccepted` (object, required)

  - `reserveAppointmentAccepted.appointment` (object, required)
    A booked appointment. `appointmentReservationKey` and `appointmentReservationValidUntil` are always present. Complex installation appointments (`orderSurvey`/`orderExternal`/`orderInternal`) carry `cfh:startDateTime`/`cfh:endDateTime`; the single-day `appointmentDate`, `appointmentStartTime` and `appointmentEndTime` are present for simple orders and for same-day complex slots, but omitted when a complex slot spans multiple days (possible for `orderExternal`).

  - `reserveAppointmentAccepted.appointment.appointmentDate` (string)
    Date of the appointment
    Example: 2012-01-20

  - `reserveAppointmentAccepted.appointment.appointmentStartTime` (string)
    Appointment start time
    Example: 08:00

  - `reserveAppointmentAccepted.appointment.appointmentEndTime` (string)
    Appointment end time
    Example: 08:00

  - `reserveAppointmentAccepted.appointment.cfh:startDateTime` (string)
    Start of the appointment as a full ISO 8601 UTC date-time. Present on complex installation appointments (`orderSurvey`, `orderExternal`, `orderInternal`). Together with `cfh:endDateTime` it is the authoritative slot boundary, and is the only representation when an appointment spans multiple days (possible for the `orderExternal` build-to-wall stage).
    Example: 2023-05-01T08:00:00Z

  - `reserveAppointmentAccepted.appointment.cfh:endDateTime` (string)
    End of the appointment as a full ISO 8601 UTC date-time. Present on complex installation appointments (`orderSurvey`, `orderExternal`, `orderInternal`). For a multi-day appointment (possible for the `orderExternal` build-to-wall stage) its date differs from `cfh:startDateTime`.
    Example: 2023-05-01T13:00:00Z

  - `reserveAppointmentAccepted.appointment.appointmentReservationKey` (string, required)
    The unique key for appointment reservation
    Example: EI7PBRU6TL8KN1YNGO8ICEUI0UDFE9M8

  - `reserveAppointmentAccepted.appointment.appointmentReservationValidUntil` (string, required)
    Reservation until date
    Example: 2012-01-20T18:30:43Z

  - `reserveAppointmentRejected` (any, required)

  - `reserveAppointmentRejected.systemError` (object)

  - `reserveAppointmentRejected.systemError.errorCode` (string)
    Error Code
    Example: CF-123-123

  - `reserveAppointmentRejected.systemError.errorMessage` (string)
    Error Message
    Example: Some failure

  - `reserveAppointmentRejected.validationFailures` (array)

  - `reserveAppointmentRejected.validationFailures.validationFailure` (object)

  - `reserveAppointmentRejected.validationFailures.validationFailure.validationFailureField` (string, required)
    Validation Failure Field
    Example: postcode

  - `reserveAppointmentRejected.validationFailures.validationFailure.validationFailureMessage` (string, required)
    Validation Failure message
    Example: Invalid Postcode

  - `reserveAppointmentRejected.errorOther` (object)

  - `reserveAppointmentRejected.errorOther.errorCode` (string, required)
    Error Code
    Example: CF-123-123

  - `reserveAppointmentRejected.errorOther.errorMessage` (string, required)
    Error Message
    Example: Some failure

## Response 400 fields (application/xml):

  - `fault` (object)

  - `fault.faultcode` (string, required)

  - `fault.faultmessage` (string, required)

  - `fault.detail` (string)

## Response 401 fields (application/xml):

  - `fault` (object)

  - `fault.faultcode` (string, required)

  - `fault.faultmessage` (string, required)

  - `fault.detail` (string)

## Response 403 fields (application/xml):

  - `fault` (object)

  - `fault.faultcode` (string, required)

  - `fault.faultmessage` (string, required)

  - `fault.detail` (string)