openapi: 3.1.0
info:
  title: Berkley API
  version: 1.0.0-BETA2
servers:
  - url: https://porter-staging.vacatia.com/api
    description: The staging API server
  - url: https://porter.vacatia.com/api
    description: The PRODUCTION API server
paths:
  /owners:
    post:
      summary: Create an owner
      tags:
        - Owners
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostOwnerRequest'
      responses:
        '201':
          description: The created owner id
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OwnerResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '422':
          description: An error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation-json'
          links: {}
  /owners/{ownerId}:
    parameters:
      - in: path
        name: ownerId
        required: true
        schema:
          type: string
          example: V-0000-0000
    patch:
      summary: Update an owner
      tags:
        - Owners
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchOwnerRequest'
      responses:
        '200':
          description: The updated owner id
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OwnerResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '422':
          description: An error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation-json'
          links: {}
  /properties:
    get:
      summary: List properties
      tags:
        - Properties
      parameters:
        - in: query
          name: pageNumber
          schema:
            type: integer
            example: 2
      responses:
        '200':
          description: A paginated list of properties
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Property'
                  - $ref: '#/components/schemas/PaginatedResponse'
  /properties/{propertyId}:
    parameters:
      - in: path
        name: propertyId
        required: true
        schema:
          type: string
          example: MT-MLR
    get:
      summary: Fetch a property
      tags:
        - Properties
      responses:
        '200':
          description: The requested property
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Property'
  /properties/{propertyId}/unit-types:
    parameters:
      - in: path
        name: propertyId
        required: true
        schema:
          type: string
          example: MT-MLR
      - in: query
        name: pageNumber
        schema:
          type: integer
          example: 2
    get:
      summary: List unit types
      tags:
        - Properties
      responses:
        '200':
          description: A paginated list of unit types
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/UnitType'
                  - $ref: '#/components/schemas/PaginatedResponse'
  /properties/{propertyId}/unit-skus:
    parameters:
      - in: path
        name: propertyId
        required: true
        schema:
          type: string
          example: MT-MLR
    get:
      summary: List unit SKUs
      tags:
        - Properties
      responses:
        '200':
          description: A paginated list of unit SKUs
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/UnitSku'
                  - $ref: '#/components/schemas/PaginatedResponse'
  /contracts:
    post:
      summary: Create a contract
      tags:
        - Contracts
      requestBody:
        description: The new contract
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contract'
      responses:
        '201':
          description: The new contract id
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PostContractResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '422':
          description: An error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation-json'
          links: {}
  /properties/{propertyId}/reservations:
    parameters:
      - in: path
        name: propertyId
        required: true
        schema:
          type: string
          example: MT-MLR
    post:
      summary: Create a reservation
      tags:
        - Reservations
      requestBody:
        description: The reservation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Reservation'
      responses:
        '201':
          description: The new reservation id and the primary guest id
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PostPatchReservationResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '422':
          description: An error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation-json'
          links: {}
  /properties/{propertyId}/reservations/{reservationId}:
    parameters:
      - in: path
        name: propertyId
        required: true
        schema:
          type: string
          example: MT-MLR
      - in: path
        name: reservationId
        required: true
        schema:
          type: string
          example: '0123456789'
    get:
      summary: Fetch a reservation
      tags:
        - Reservations
      responses:
        '200':
          description: The requested reservation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Reservation'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
    patch:
      summary: Update a reservation
      tags:
        - Reservations
      requestBody:
        description: The reservation changes
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchReservationRequest'
      responses:
        '200':
          description: The updated reservation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PostPatchReservationResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '422':
          description: An error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation-json'
          links: {}
  /properties/{propertyId}/reservations/{reservationId}/guests:
    parameters:
      - in: path
        name: propertyId
        required: true
        schema:
          type: string
          example: MT-MLR
      - in: path
        name: reservationId
        required: true
        schema:
          type: string
          example: '0123456789'
    post:
      summary: Adds a guest to reservation as an additional guest.
      tags:
        - Guests
      requestBody:
        description: The new guest
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostGuestRequest'
      responses:
        '201':
          description: Guest resource created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPatchGuestResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '422':
          description: An error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation-json'
          links: {}
  /properties/{propertyId}/guests/{guestId}:
    parameters:
      - in: path
        name: propertyId
        required: true
        schema:
          type: string
          example: MT-MLR
      - in: path
        name: guestId
        required: true
        schema:
          type: string
          example: '0123456789'
    get:
      summary: Fetch a guest
      tags:
        - Guests
      responses:
        '200':
          description: The requested guest
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Guest'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
    patch:
      summary: Update a guest
      tags:
        - Guests
      requestBody:
        description: The guest changes
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchGuestRequest'
      responses:
        '200':
          description: The updated guest
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PostPatchGuestResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '422':
          description: An error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation-json'
          links: {}
components:
  schemas:
    PaginatedResponse:
      type: object
      properties:
        pageNumber:
          type: integer
          description: The current page number
        pageSize:
          type: integer
          description: The number of records on each page
        totalPages:
          type: integer
          description: The total number of pages
    Guest:
      type: object
      required:
        - firstName
        - lastName
        - emailAddress
        - mailingAddress
      properties:
        id:
          type: string
          description: The Cloudbeds guest ID
          readOnly: true
        vacatiaOwnerId:
          type: string
          description: The Vacatia guest ID
          example: V-0000-0000
        firstName:
          type: string
          description: The guest's first name
          example: James
        lastName:
          type: string
          description: The guest's last name
          example: Kirk
        emailAddress:
          type: string
          format: email
          description: The guest's email address
        mailingAddress:
          $ref: '#/components/schemas/Address'
          description: The guest's mailing address
        homePhone:
          type: string
          description: The guest's home phone number
        mobilePhone:
          type: string
          description: The guest's mobile phone number
    PostGuestRequest:
      type: object
      required:
        - firstName
        - lastName
      properties:
        vacatiaOwnerId:
          type: string
          description: The Vacatia guest ID
          example: V-0000-0000
        firstName:
          type: string
          description: The guest's first name
          example: Kathryn
        lastName:
          type: string
          description: The guest's last name
          example: Janeway
        emailAddress:
          type: string
          format: email
          description: The guest's email address
        mailingAddress:
          $ref: '#/components/schemas/Address'
          description: The guest's mailing address
        homePhone:
          type: string
          description: The guest's home phone number
        mobilePhone:
          type: string
          description: The guest's mobile phone number
    PatchGuestRequest:
      type: object
      properties:
        firstName:
          type: string
          description: The guest's first name
          example: James
        lastName:
          type: string
          description: The guest's last name
          example: Kirk
        emailAddress:
          type: string
          format: email
          description: The guest's email address
        mailingAddress:
          $ref: '#/components/schemas/Address'
          description: The guest's mailing address
        homePhone:
          type: string
          description: The guest's home phone number
        mobilePhone:
          type: string
          description: The guest's mobile phone number
    PostPatchGuestResponse:
      type: object
      properties:
        id:
          type: string
          description: The Cloudbeds guest ID
          readOnly: true
    ReservationNote:
      type: object
      required:
        - note
      properties:
        id:
          type: string
          readOnly: true
          description: The Cloudbeds reservation note ID
        createdAt:
          type: string
          format: date-time
          readOnly: true
        note:
          type: string
          description: The note text
          example: Please note that the example guest is allergic to example peanuts.
    Reservation:
      type: object
      required:
        - source
        - startDate
        - endDate
        - accommodations
        - primaryGuest
      properties:
        id:
          type: string
          description: The Cloudbeds reservation ID
          readOnly: true
        cloudbedsSource:
          type: string
          description: >-
            The Cloudbeds source name (e.g. "Marketing, Exchange - RCI [Owner
            Home Week], Exchange - RCI [Guest-NC]")
          readOnly: true
        sourceId:
          type: string
          description: >-
            The id of the reservation in the third-party system, the
            reservation's SPI Itinerary ID or RCI Reservation ID for instance.
          readOnly: false
        source:
          type: string
          enum:
            - exchange
            - marketing
          description: Used in selecting the room type waterfall
          writeOnly: true
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        status:
          type: string
          enum:
            - not_confirmed
            - confirmed
            - canceled
            - checked_in
            - checked_out
            - no_show
        exchangeName:
          type: string
          enum:
            - rci
          description: The name of the exchange company (e.g. "RCI")
        exchangeGuestType:
          type: string
          enum:
            - resort_home_week_owner
            - resort_owner
            - berkley_owner
            - exchange_member
            - exchange_member_guest
          description: The type of guest (e.g. "owner")
        requestedAdaUnit:
          type: boolean
          description: Whether the guest requested an ADA unit
          default: false
        reservationType:
          type: string
        reservationSubtype:
          type: string
        rciMemberId:
          type: string
          description: The RCI member ID
        primaryGuest:
          $ref: '#/components/schemas/Guest'
        additionalGuests:
          type: array
          items:
            $ref: '#/components/schemas/Guest'
        accommodations:
          type: array
          items:
            $ref: '#/components/schemas/Accommodation'
          description: A list of accommodations (must include at least one item)
        notes:
          writeOnly: true
          type: array
          items:
            $ref: '#/components/schemas/ReservationNote'
    PatchReservationRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - not_confirmed
            - confirmed
            - canceled
            - checked_in
            - checked_out
            - no_show
        reservationType:
          type: string
        reservationSubType:
          type: string
        rciMemberId:
          type: string
          description: The RCI member ID
    PostPatchReservationResponse:
      type: object
      properties:
        reservationId:
          type: string
          description: The Cloudbeds reservation ID
          example: '134782164'
        primaryGuest:
          type: object
          description: The reservation's primary guest
          properties:
            id:
              type: string
              description: The Cloudbeds guest ID
              example: '131556374'
    Accommodation:
      type: object
      required:
        - unitTypeCode
        - numberOfAdults
      properties:
        id:
          type: string
          readOnly: true
        roomTypeName:
          type: string
          readOnly: true
        roomName:
          type: string
          readOnly: true
        unitTypeCode:
          type: string
          example: WEST A
          description: Used in selecting the room type waterfall
          writeOnly: true
        numberOfAdults:
          type: integer
          minimum: 1
        numberOfChildren:
          type: integer
          minimum: 0
    Property:
      type: object
      properties:
        id:
          type: string
          example: MT-MLR
        name:
          type: string
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    UnitSku:
      type: object
      properties:
        propertyId:
          type: string
        code:
          type: string
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    UnitType:
      type: object
      properties:
        propertyId:
          type: string
        code:
          type: string
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
          description: The ISO 3166-1 alpha-2 country code
    Tag:
      type: object
      required:
        - code
      properties:
        code:
          type: string
        value:
          type:
            - string
            - 'null'
    PostOwnerRequest:
      type: object
      required:
        - lastName
      properties:
        id:
          type: string
          readOnly: true
          example: V-0000-0000
        ownerType:
          type: string
          enum:
            - individual
            - individual_legal_representative
            - corp_llc
            - trust
            - entity_legal_representative
          default: individual
        socialSecurityNumber:
          type: string
          description: The owner's social security number (SSN)
          example: 123-45-6789
        salutation:
          type: string
          examples:
            - Mr.
            - Ms.
            - Mrs.
            - Dr.
            - Prof.
        firstName:
          type: string
        middleName:
          type: string
        lastName:
          type: string
        suffix:
          type: string
          examples:
            - Jr
            - Sr
            - I
            - II
            - III
        emailAddress:
          type: string
          format: email
        homePhoneNumber:
          type: string
        mobilePhoneNumber:
          type: string
        workPhoneNumber:
          type: string
        mailingAddress:
          $ref: '#/components/schemas/Address'
          description: The guest's mailing address
        billingAddress:
          $ref: '#/components/schemas/Address'
          description: The guest's billing address
    PatchOwnerRequest:
      type: object
      properties:
        salutation:
          type: string
          examples:
            - Mr.
            - Ms.
            - Mrs.
            - Dr.
            - Prof.
        emailAddress:
          type: string
          format: email
        homePhoneNumber:
          type: string
        mobilePhoneNumber:
          type: string
        workPhoneNumber:
          type: string
        mailingAddress:
          $ref: '#/components/schemas/Address'
          description: The guest's mailing address
        billingAddress:
          $ref: '#/components/schemas/Address'
          description: The guest's billing address
    OwnerResponse:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: V-0000-0000
    Contract:
      type: object
      required:
        - propertyId
        - frequency
        - usage
        - unitSkuCode
        - seasonCode
        - purchaseDate
        - firstOccupancyYear
      properties:
        id:
          type: string
          readOnly: true
          example: MLR-12345
        legacyContractId:
          type: string
          example: 12345
          description: The legacy contract ID (spiContractId for instance)
        propertyId:
          type: string
          example: MT-MLR
        frequency:
          type: string
          enum:
            - A
            - E
            - O
            - T0
            - T1
            - T2
        usage:
          type: string
          enum:
            - fixed_interval_fixed_unit
            - fixed_interval_float_unit
            - float_interval_fixed_unit
            - float_interval_float_unit
        unitSkuCode:
          type: string
          example: 101AB
        intervalSkuCode:
          type: string
          example: '52'
        status:
          type: string
          enum:
            - active
            - terminated
            - transferred
          readOnly: true
        purchaseDate:
          type: string
          format: date
          description: The purchase date (i.e. contract date)
        firstOccupancyYear:
          type: integer
          example: 2030
        amount:
          type: string
          example: '1000.00'
        terminationDate:
          type: string
          format: date
          readOnly: true
        rciPoints:
          type: boolean
          default: false
        primaryOwnerId:
          type: string
          example: V-0000-0000
        secondaryOwnerId:
          type: string
          example: V-0000-0000
        additionalOwnerIds:
          type: array
          items:
            type: string
            example: V-0000-0000
        transferSourceIds:
          type: array
          items:
            type: string
            example: MLR-12345
    PostContractResponse:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: MLR-12345
    ConstraintViolation-json:
      type: object
      description: Unprocessable entity
      deprecated: false
      properties:
        status:
          default: 422
          example: 422
          type: integer
        violations:
          type: array
          items:
            type: object
            properties:
              propertyPath:
                type: string
                description: The property path of the violation
              message:
                type: string
                description: The message associated with the violation
        detail:
          readOnly: true
          type: string
        type:
          readOnly: true
          type: string
        title:
          readOnly: true
          type:
            - string
            - 'null'
        instance:
          readOnly: true
          type:
            - string
            - 'null'
    Error:
      type: object
      description: A representation of common errors.
      deprecated: false
      properties:
        title:
          readOnly: true
          description: A short, human-readable summary of the problem.
          type:
            - string
            - 'null'
        detail:
          readOnly: true
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          type:
            - string
            - 'null'
        status:
          type: number
          example: 404
          default: 400
        instance:
          readOnly: true
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem. It may or may not yield further information if
            dereferenced.
          type:
            - string
            - 'null'
        type:
          readOnly: true
          description: A URI reference that identifies the problem type
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []
