openapi: "3.0.0"
info:
  version: 1.0.0
  title: Common Mortgage API (Public)
  description: 
    This specification defines a common mortgage API for mortgages as used in Switzerland. The API is supposed to be used by requesting parties who want to get, extend, or transfer mortgages from and to financial institutions.
    This specification uses schema definitions from the Common Data Model v1.2.2.
  termsOfService: 'Tbd'
  contact:
    email: info@common-api.ch
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: mortgage.common-api.ch
externalDocs:
  description: Find out more about SFTI API specifications
  url: 'https://www.common-api.ch'
tags:
  - name: Existing Mortgages
    description: Operations related with existing mortgages
  - name: Mortgage Products and Conditions
    description: Operations for synchronizing general mortgage product information from an FI
  - name: Mortgage Application
    description: Operations needed to place an application (dossier) for a new mortgage
  - name: Mortgage Financing Request
    description: Operations for handling financing requests for a specific accepted application (dossier)
  - name: Mortgage Offers
    description: Operations for handling the binding offers an FI provides
  - name: Mortgage Order
    description: Operations for placing a binding order for a chosen offer
  - name: Mortgage Prolongation
    description: Operations for handling the common special case of prolonging an existing mortgage
security:
  - ApiKeyAuth: []
  - OAuth2:
      - read
      - write
paths:
  /mortgages:
    get:
      tags: 
        - Existing Mortgages
      description: List of mortgages for the authenticated context including the corresponding properties and related mortgages, sorted by mortgageId.
      summary: Return the list of all mortgages for the authenticated context
      parameters:
        - in: query
          name: expiring
          schema:
            type: boolean
          example: true
          description: Whether or not the mortgage is qualified for being prolonged, i.e., expiring soon or already expired (for filtering)
        - in: query
          name: limit
          schema:
            type: integer
          example: 25
          description: Optional parameter for pagination. Maximum number of entries to be returned.
        - in: query
          name: offset
          schema:
            type: integer
          example: 26
          description: Optional parameter for pagination. Start entry to be returned.
      responses:
        '200':
          description: Paginated list of all mortgages with all related information sorted by mortgageId
          content:
            application/json:
              schema:
                type: object
                properties:
                  MortgageList: 
                    type: array
                    items:
                      $ref: '#/components/schemas/Mortgage'
                  _links:
                    $ref: '#/components/schemas/Links'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'


  /mortgages/{mortgageId}:
    get:
      tags:
        - Existing Mortgages
      description: A specific existing mortgage including the corresponding properties and related mortgages.
      summary: Return a specific existing mortgage
      parameters:
        - name: mortgageId
          in: path
          description: ID of a specific existing mortgage
          required: true
          example: bankx-mortgage-234434
          schema:
            type: string
      responses:
        '200':
          description: Mortgage details with the corresponding properties and related mortgages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Mortgage: 
                    $ref: '#/components/schemas/Mortgage'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /mortgages/products:
    get:
      summary: Get a list of all mortgage products
      description: Get a complete overview of all available mortgage products sorted by productId
      tags:
        - Mortgage Products and Conditions
      parameters:
        - in: query
          name: interestRateType
          schema:
            type: string
            example: saron
            enum:
              - variable
              - libor
              - saron
              - fixed
          description: The type of the interest rates (for filtering)
        - in: query
          name: interestBasis
          schema:
            type: string
          description: The basis of the interest (for filtering)
        - in: query
          name: durationType
          schema:
            type: integer
            minimum: 1
            maximum: 20
          example: 10
          description: The type of duration (for filtering)
        - in: query
          name: limit
          schema:
            type: integer
          example: 25
          description: Optional parameter for pagination. Maximum number of entries to be returned.
        - in: query
          name: offset
          schema:
            type: integer
          example: 26
          description: Optional parameter for pagination. Start entry to be returned.
      responses:
        '200':
          description: Paginated list of all mortgage products with all related information sorted by productId
          content:
            application/json:
              schema:
                type: object
                properties:
                  productList: 
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  _links:
                    $ref: '#/components/schemas/Links'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'


  /mortgages/products/{productId}/conditions:
    get:
      summary: Get the general conditions for the specified mortgage product
      description: The standard financial conditions for the product
      tags:
        - Mortgage Products and Conditions
      parameters:
        - in: path
          name: productId
          schema:
            type: string
          required: true
          example: bankx-product-234
          description: A product's unique ID
        - in: query
          name: duration
          schema:
            type: string
          description: The duration (for filtering)
        - in: query
          name: interest
          schema:
            type: string
          description: The interest (for filtering)
      responses:
        '200':
          description: List of conditions related to a specific mortgage product.
          content:
            application/json:
              schema:
                type: object
                properties:
                  conditionList: 
                    type: array
                    items:
                      $ref: '#/components/schemas/Condition'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
          

  /mortgages/applications:
    post:
      summary: Place a new mortgage application (serves as dossier)
      description: Place a new application including all necessary information about the property and applicant’s financial situation. **Note that in the case where the FI needs additional information on the property, the error response 400 must contain the minimum required JSON object (PropertyObject) as detail**.
      tags:
        - Mortgage Application
      requestBody:
        description: Static details (requesting party, property object) of the application to be added as a dossier
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
      responses:
        '201':
          description: created
          headers:
            location:
              schema:
                type: string
                format: uri
                description: link to the created resource
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
  
  /mortgages/applications/required-information:
    get:
      summary: Get the required property information for the specific FI needed for valuation
      description: Show the subset of property details required by the FI for valuation
      tags:
        - Mortgage Application
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PropertyObject'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

                        
  /mortgages/applications/{applicationId}:
    get:
      summary: Get the details of a specific placed application
      description: Get the details of a specific placed application
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          required: true
          example: bankx-applicationreq-465234
          description: Unique ID of the application request
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  application:
                    $ref: '#/components/schemas/Application'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

    put:
      summary: Update the application’s details
      description: Update the application’s details. Note that changing the application's details should not be possible after the application has been accepted by the FI.
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          required: true
          example: bankx-applicationreq-465234
          description: Unique ID of the application request
      requestBody:
        description: Details of the order to be added
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

    delete:
      summary: Cancel the application and removing it
      description: Cancel the application and removing it
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          required: true
          example: bankx-applicationreq-465234
          description: Unique ID of the application request
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'


  /mortgages/applications/{applicationId}/swissrets:
    post:
      summary: Add property details in the SwissRETS standard
      description: This endpoint allows to upload the real estate property's details as an XML file in the SwissRETS format according to https://swissrets.ch/ 
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          required: true
          example: bankx-applicationreq-465234
          description: Unique ID of the application request
      requestBody:
        description: Details of the real estate property to be added
        required: true
        content:
          application/xml:
            schema:
              type: string
      responses:
        '201':
          description: created
          headers:
            location:
              schema:
                type: string
                format: uri
                description: link to the created resource
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

    get:
      summary: Get property details in SwissRETS format
      description: Get the real estate property's details in SwissRETS format XML according to https://swissrets.ch/
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          example: bankx-applicationreq-465234
          required: true
          description: Unique ID of the application request
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
    put:
      summary: Update the real estate property's details
      description: This endpoint allows to upload a modified XML file in the SwissRETS format changing the already existing information
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          required: true
          example: bankx-applicationreq-465234
          description: Unique ID of the application request
      requestBody:
        description: Details of the real estate property to be added
        required: true
        content:
          application/xml:
            schema:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /mortgages/applications/{applicationId}/documents:
    post:
      summary: Add documents for the specific application
      description: Add to a specific application’s documents
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          required: true
          example: bankx-applicationreq-465234
          description: Unique ID of the application request
      requestBody:
        description: Details of the document to be added
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filename:
                  type: string
                  format: binary
      responses:
        '201':
          description: created
          headers:
            location:
              schema:
                type: string
                format: uri
                description: link to the created resource
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

    get:
      summary: Get a list of submitted documents for a specifically placed application
      description: Get a list of documents submitted for a specifically placed application
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          example: bankx-applicationreq-465234
          required: true
          description: Unique ID of the application request
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: object
                  properties:
                    filename: 
                      type: string
                    filetype:
                      type: string
                    filesize:
                      type: integer
                    uploaddate:
                      $ref: '#/components/schemas/Date'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'


  /mortgages/applications/{applicationId}/documents/{documentId}:               
    delete:
      summary: Delete a formerly uploaded document
      description: Deletes a specific document attached to a specific application. Note that deleting documents should not be possible after the application has been accepted by the FI.
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          example: bankx-applicationreq-465234
          required: true
          description: Unique ID of the application (dossier)
        - in: path
          name: documentId
          schema:
            type: string
          example: bankx-application-document-3445
          required: true
          description: Unique ID of the document
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
  
  /mortgages/applications/{applicationId}/status:
    get:
      summary: Get the current status of the application 
      description: Get the current status of the application (rejected with reason, accepted, pending with reason)
      tags:
        - Mortgage Application
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          example: bankx-applicationreq-465234
          required: true
          description: Unique ID of the application request
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - accepted
                      - rejected
                      - pending
                    example: pending
                  detail:
                    type: string
                    example: Waiting for details
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'  
  
  /mortgages/applications/{applicationId}/financing-requests:
    post:
      summary: Place a new financing-request for a specific accepted application (dossier)
      description: Place a new financing request including all necessary information
      tags:
        - Mortgage Financing Request
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          example: bankx-applicationreq-465234
          required: true
          description: Unique ID of the application request
      requestBody:
        description: Specific financing request fo the given application (dossier)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinancingRequest'
      responses:
        '201':
          description: created
          headers:
            location:
              schema:
                type: string
                format: uri
                description: link to the created resource
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /mortgages/applications/{applicationId}/financing-requests/{financingRequestId}/offers:
    get:
      summary: List all binding offers for a given financing request
      description: List all binding offers for a given application
      tags:
        - Mortgage Offers
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          example: bankx-applicationreq-465234
          required: true
          description: Unique ID of the application request
        - in: path
          name: financingRequestId
          schema:
            type: string
          example: bankx-financingreq-35623
          required: true
          description: Unique ID of the financing request
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  offerList: 
                    type: array
                    items:
                      $ref: '#/components/schemas/Offer'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  
  /mortgages/applications/{applicationId}/financing-requests/{financingRequestId}/offers/{offerId}:
    get:
      summary: Get the details of a specific offer
      description: Get the details of a specific offer for a specific placed application
      tags:
        - Mortgage Offers
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
          example: bankx-applicationreq-465234
          required: true
          description: Unique ID of the application request
        - in: path
          name: financingRequestId
          schema:
            type: string
          example: bankx-financingreq-35623
          required: true
          description: Unique ID of the financing request
        - in: path
          name: offerId
          schema:
            type: string
          example: bankx-offer-35465
          required: true
          description: Unique ID of the offer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  offer:
                    $ref: '#/components/schemas/Offer'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  
  /mortgages/orders:
    post:
      summary: Place a new order
      description: Place a new order referencing a specific offerId and either an existing mortgage id (prolongation) or an application id (new mortgage) including all relevant information
      tags:
        - Mortgage Order
      requestBody:
        description: Details of the order to be added
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: created
          headers:
            location:
              schema:
                type: string
                format: uri
                description: link to the created resource
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
  
  /mortgages/orders/{orderId}:
    get:
      summary: Get the details of a specific placed order
      description: Get the details of a specific placed order
      tags:
        - Mortgage Order
      parameters:
        - in: path
          name: orderId
          schema:
            type: string
          example: bankx-order-6464
          required: true
          description: Unique ID of an order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  offer:
                    $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  
  /mortgages/orders/{orderId}/status:
    get:
      summary: Get the current status of the order
      description: Get the current status of the order (rejected with reason, accepted, pending with reason)
      tags:
        - Mortgage Order
      parameters:
        - in: path
          name: orderId
          schema:
            type: string
          example: bankx-order-6464
          required: true
          description: Unique ID of an order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - accepted
                      - rejected
                      - pending
                    example: pending
                  detail:
                    type: string
                    example: Waiting for details
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
                    
  /mortgages/{mortgageId}/offers:
    get:
      tags:
        - Mortgage Prolongation
      description: Get offer framework for the to be extended mortgage.
      summary: Get all active offers for a specific tranche
      parameters:
        - name: mortgageId
          in: path
          description: ID of a specific expiring mortgage
          required: true
          example: bankx-mortgage-354663
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of all offers for a specific expiring mortgage
          content:
            application/json:
              schema:
                type: object
                properties:
                  offerList: 
                    type: array
                    items:
                      $ref: '#/components/schemas/Offer'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  
  /mortgages/{mortgageId}/offers/{offerId}:
    get:
      tags:
        - Mortgage Prolongation
      description: Get a specific offer for the to be extended mortgage.
      summary: Get a specific offer for a specific tranche
      parameters:
        - name: mortgageId
          in: path
          description: ID of a specific expiring mortgage
          example: bankx-mortgage-354663
          required: true
          schema:
            type: string
        - name: offerId
          in: path
          description: ID of a specific mortgage prolongation offer
          example: bankx-offer-35465
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Specific offer for a specific expiring mortgage
          content:
            application/json:
              schema:
                type: object
                properties:
                  offer:
                    $ref: '#/components/schemas/Offer'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
                
# -------------------------
# -------- Models ---------
# -------------------------
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access

  schemas:
    # ---- Common Data Model v1.2.0
    # ---- Date Formats
    Date:
      type: string
      format: date
      example: 2018-04-13
        
    DateTime:
      type: string
      format: date-time
      example: 2018-04-13T11:11:11Z
    # --------
    # ---- Links ----
    Links:
      description: links returned in the answer of an API call
      type: object
      properties:
        self:
          type: string
        first:
          type: string
        previous:
          type: string
        next:
          type: string
        last:
          type: string 
    # ---------
    # ---- Currency ----
    Currency:
      description: ISO 4217 code
      type: string
      pattern: '[A-Z]{3}'
      example: CHF
    # ---------
    # ---- Amount ----
    Amount:
      description: amount with currency
      type: object
      required:
        - currency
        - content
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        content:
          description: amount given with fractional digits, the separator is a dot
          type: string
          pattern: '-?\d{1,14}(?:\.\d{1,3})?'
          example: 235.45
    # --------
    # ---- Address compliant to payment address (b.Link & ISO20022)----
    structuredAddress:
      title: Structured Address
      type: object
      required:
        - streetName
        - postCode
        - townName
        - country
      properties:
        streetName:
          type: string
          maxLength: 70
          example: "Rue de la gare"
        buildingNumber:
          type: string
          maxLength: 16
          example: "24"
        postCode:
          type: string
          maxLength: 16
          example: "2501"
        townName:
          type: string
          maxLength: 35
          example: "Biel"
        country:
          type: string
          maxLength: 2
          example: "CH"

    unstructuredAddress:
      title: Unstructured Address
      type: object
      required:
        - addressLines
        - country
      properties:
        addressLines:
          type: array
          description: max 2 lines of 70 characters
          maxLength: 2
          example: ["Robert Schneider SA", "Rue de la gare 24"]
          items:
            type: string
            maxLength: 70
        country:
          type: string
          maxLength: 2
          example: "CH"

    structuredOrUnstructuredAddress:
      title: Structured or Unstructured Address
      description: Either structured or unstructered must be set
      type: object
      properties:
        structured:
          $ref: '#/components/schemas/structuredAddress'
        unstructured:
          $ref: '#/components/schemas/unstructuredAddress'
    # -----------
    # ---- Country Code ----
    Country:
      type: string
      pattern: '[A-Z]{2}'
      example: CH
      description: 2-Letter ISO 3166-2 Country Code
    # ------------
    # ---- Error Response (compliant to SIX b.Link)
    commonErrorResponse:
      title: Common Error Response
      type: object
      properties:
        type:
          $ref: '#/components/schemas/commonErrorType'
        title:
          type: string
          example:
            This is the general problem description
        detail:
          type: string
          example:
            Detailed problem description with respect to the current request
        instance:
          type: string
          example:
            path/to/corresponding/resource

    commonErrorType:
      title: Common Error Type
      description: Error Types for commonErrorResponse.
      type: string
      enum:
        - /problems/INVALID_PAYLOAD
        - /problems/MALFORMED_PAYLOAD
        - /problems/INVALID_TOKEN
        - /problems/EXPIRED_TOKEN
        - /problems/INSUFFICIENT_PRIVILEGES
        - /problems/NO_ACCESS_TO_RESOURCE
        - /problems/RESOURCE_DOES_NOT_EXIST
        - /problems/RESOURCE_NOT_READY
        - /problems/RESOURCE_TOO_LARGE
        - /problems/WRONG_METHOD
        - /problems/OPERATION_NOT_ALLOWED
        - /problems/TECHNICAL_ERROR
        - /problems/NOT_IMPLEMENTED
        - /problems/SERVICE_UNAVAILABLE
      example: '/problems/TECHNICAL_ERROR'
    # ---- End Error Response
    # ---- End Common Data Model

    # ---- Property Object ----
    PropertyObject:
      description: The representation of a real estate object, real estate register id (propertyIdentifier) is optional until otherwise required by law
      type: object
      required:
        - propertyObjectId
        - name
        - address
      properties:
        propertyObjectId:
          type: string
          example: propertyID-436563
        name:
          type: string
          example: My Nice Property
        objectType:
          type: string
          example: house
          enum:
          - apartment
          - house
          - garage
          - other
        #### At the moment we consider only mortgages for self-occupied real estate
        #usageType:
        #  type: string
        address:
          $ref: '#/components/schemas/structuredAddress'
        propertyIdentifier:
          $ref: '#/components/schemas/PropertyIdentifier'
        luxuryLevel:
          type: string
          example: yes
          enum:
          - 'yes'
          - 'no'
        landArea:
          type: integer
        netDwellingArea:
          type: integer
        volume:
          type: object
          properties:
            amount: 
              type: integer
            standard:
              type: string
              #enum:
              # what standards are considered?
        buildYear:
          type: integer
          example: 1929
        lastRenovationYear:
          type: integer
          example: 1980
        buildingCondition: # Range?
          type: integer
        buildingQuality: # Range?
          type: integer
        rooms:
          type: number
          example: 4
        roomCountingStrategy:
          type: string
        bathRooms:
          type: integer
          example: 2
        closets:
          type: integer
          example: 1
        parkingLots:
          type: integer
          example: 4
        undergroundParkingLots:
          type: integer
          example: 0
        dedicatedGarages:
          type: integer
          example: 1
        minergieStandard:
          type: string
          #enum: 
          # values?
        valueRelevantServitudes:
          type: string
        objectPrice:
          type: integer
          example: 3544344
        purchaseDate:
          $ref: '#/components/schemas/Date'
        remarks:
          type: string
    # ---------
    
    # ---- Property Identifier ----
    PropertyIdentifier:
      description: Property identification (register of real estate)
      type: object
      properties:
        EGRID:
          type: string
        EGID:
          type: string 
    # ---------

    # ---- Mortgage ----
    Mortgage:
      description: All relevant information regarding a specific mortgage
      type: object
      required:
        - mortgageId
        - product
        - amountAtExpiry
        - validFrom
        - validTo
        - interestRate
        - interestRateType
        - interestBasis
        - durationType
        - prolongable
        - propertyObjects
        - linkRef
      properties:
        mortgageId:
          type: string
          example: bankx-mortgage-354663
        product:
          $ref: '#/components/schemas/Product'
        amountAtExpiry:
          $ref: '#/components/schemas/Amount'
        amountToday:
          $ref: '#/components/schemas/Amount'
        validFrom:
          $ref: '#/components/schemas/Date'
        validTo:
          $ref: '#/components/schemas/Date'
        interestRate:
          type: string
        interestRateType:
          type: string
          example: libor
          enum:
            - variable
            - libor
            - saron
            - fixed
        interestBasis:
          type: string
        durationType:
          type: integer
          example: 10
          minimum: 1
          maximum: 20
        prolongable:
          type: boolean
        propertyObjects:
          type: array
          items:
            $ref: '#/components/schemas/PropertyObject'
        relatedMortgages:
          type: array
          items:
            $ref: '#/components/schemas/Mortgage'
        linkRef:
          type: string   
    # ---------
    
    # ---- Mortgage Offer ----
    Offer:
      description: All relevant details describing the FI's offer for a mortgage product
      type: object
      required:
        - offerId
        - financingRequestIdRef
        - totalAmount
        - validTo
        - offerItems
        - linkRef
      properties:
        offerId:
          type: string
          example: bankx-offer-35465
        financingRequestIdRef:
          type: string
          example: bankx-applicationreq-465234
        totalAmount:
          $ref: '#/components/schemas/Amount'
        validTo:
          $ref: '#/components/schemas/Date'
        offerItems: 
          type: array
          items:
            $ref: '#/components/schemas/OfferItem'
        linkRef:
          type: string
    # ---------

    # ---- Mortgage Offer Item ----
    OfferItem:
      description: All relevant details of a specific item being part of an FI's offer for a mortgage product
      type: object
      required:
        - offerItemId
        - product
        - conditions
      properties:
        offerItemId:
          type: string
          example: bankx-offer-35465
        product:
          $ref: '#/components/schemas/Product'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/Condition'
    # ---------

    # ---- Mortgage Product ----
    Product:
      description: All details regarding an FI's mortgage product
      type: object
      required:
        - productId
        - name
        - interestRateType
        - interestBasis
        - durationType
      properties:
        productId:
          type: string
          example: bankx-product-234
        name:
          type: string
          example: Nice Mortgage Product Large
        interestRateType:
          type: string
          example: libor
          enum:
            - variable
            - libor
            - saron
            - fixed
        interestBasis:
          type: string
        durationType:
          type: integer
          example: 10
          minimum: 1
          maximum: 20
    # ---------

    # ---- Mortgage Product Condition ----
    Condition:
      description: All details regarding the conditions for a specific mortgage product the FI offers
      type: object
      required:
        - conditionId
        - productIdRef
        - duration
        - maturityDate
        - interest
        - amountRange
        - increment
      properties:
        conditionId:
          type: string
          example: bankx-condition-45434
        productIdRef: 
          type: string
          example: bankx-product-234
        duration:
          type: string
        maturityDate:
          $ref: '#/components/schemas/Date'
        interest:
          $ref: '#/components/schemas/Interest'
        amountRange:
          $ref: '#/components/schemas/AmountRange'
        increment:
          type: integer
    # ---------

    # ---- Party ----
    Party:
      description: Links together the persons building the applicant party
      type: object
      required:
        - personList
      properties:
        personList:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/Applicant'
    # ---------

    # ---- Application ----
    Application:
      description: All static application information needed by the FI to create binding offers
      type: object
      required:
        - applicationId
        - requestingParty
        - propertyInformation
      properties:
        applicationId:
          type: string
          example: bankx-application-46543
        requestingParty:
          $ref: '#/components/schemas/Party'
        propertyInformation:
          $ref: '#/components/schemas/PropertyObject'
    # ---------

    # ---- Financing Request ----
    FinancingRequest:
      description: Based on the application, several financing requests can be sent to the FI
      type: object
      required:
        - financingRequestId
        - applicationIdRef
        - amount
      properties:
        financingRequestId:
          type: string
          example: bankx-applicationreq-465234
        applicationIdRef:
          type: string
          example: bankx-application-46543
        amount:
          $ref: '#/components/schemas/Amount'
        tranches:
          type: array
          items:
            type: object
            properties:
              productId:
                type: integer
              amount:
                $ref: '#/components/schemas/Amount'
        usedAssets:
          type: object
          properties:
            amountTotal:
              type: integer
            amountPledged:
              type: integer
        payOutDate:
          $ref: '#/components/schemas/Date'
        publicCertDate:
          $ref: '#/components/schemas/Date'
    # ---------

    # ---- Applicant ----
    Applicant:
      description: Applicant information needed by the FI for creating a binding offer
      type: object
      required:
        - applicantType
        - applicantDetail
      properties:
        applicantType:
          type: string
          enum:
          - individual
          - legal entity
        applicantDetail:
          type: object
          properties:
            name:
              type: string
              maxLength: 70
              example: Muster
            surName:
              type: string
              maxLength: 70
              example: Max
            address:
              $ref: '#/components/schemas/structuredAddress'
            birthDate:
              $ref: '#/components/schemas/Date'
            maritalStatus:
              type: string
              example: married
              enum:
              - unmarried
              - married
              - divorced
              - widowed
            matrimonialPropertyScheme:
              type: string
              example: separateEstate
              enum:
              - jointEstate
              - separateEstate
              - contributionToJointlyAcquiredProperty
            jobSituation:
              type: string
              example: employed
              enum:
              - employed
              - selfEmployed
              - unemployed
              - retired
            nationality:
              $ref: '#/components/schemas/Country'
            USPerson:
              type: boolean
              example: false
            email:
              type: string
              example: max.muster@domain.ch
            applicantLanguage:
              type: string
              example: fr
              enum:
              - de
              - fr
              - it
              - en
        financialSituation:
          type: object
          properties:
            income:
              type: array
              items:
                type: object
                properties:
                  incomeType:
                    type: string
                    example: salary
                    enum:
                    - salary
                    - pension
                    - alimony
                    - rent
                    - other
                  amount:
                    $ref: '#/components/schemas/Amount'
                  remark:
                    type: string
            ######## Special case for applicants running into retirement age: Postponed for the moment
            #estimatedRetirementIncome:
            #  $ref: '#/components/schemas/Amount'
            liabilities:
              type: array
              items:
                type: object
                properties:
                  liabilityType:
                    type: string
                    example: mortgage
                    enum:
                    - leasing
                    - alimony
                    - mortgage
                    - other
                  amount:
                    $ref: '#/components/schemas/Amount'
                  remark:
                    type: string
            assets:
              type: array
              items:
                type: object
                properties:
                  assetCategory:
                    type: string
                    example: cash
                    enum:
                    - cash
                    - thirdPillar
                    - pensionFund
                    - fungibleInvestments
                    - other
                  valuation:
                    $ref: '#/components/schemas/Amount'  
    # ---------

    # ---- Order ----
    Order:
      description: All information needed to choose a specific offer and place a binding order. If it is a prolongation, then the mortgageId of the expiring mortgage must be referenced. Otherwise the applicationId of the application for a new mortgage. Note that the prolongation use case can also be handled by the new mortgage use case (special case).
      type: object
      required:
        - offerId
        - amount
        - offeredInterest
      properties:
        offerId:
          type: string
          example: bankx-offer-35465
        mortgageId:
          type: string
          example: bankx-mortgage-234434
        applicationId:
          type: string
          example: bankx-application-46543
        amount:
          $ref: '#/components/schemas/Amount'
        offeredInterest:
          $ref: '#/components/schemas/Interest'
        validateOnly:
          type: boolean
          example: true
        status:
          type: string
    # ---------

    # ---- AmountRange ----
    AmountRange:
      description: Min and max amount with currency
      type: object
      required:
        - currency
        - minContent
        - maxContent
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        minContent:
          description: min amount given with fractional digits, the separator is a dot
          type: string
          pattern: '-?\d{1,14}(?:\.\d{1,3})?'
          example: 1000000
        maxContent:
          description: max amount given with fractional digits, the separator is a dot
          type: string
          pattern: '-?\d{1,14}(?:\.\d{1,3})?'
          example: 5000000
    # ---------

    # ---- Interest ----
    Interest:
      description: The current rate and optionally the referred base
      type: object
      required:
        - currentRate
      properties:
        currentRate:
          type: string
          pattern: '-?\d{1,3}(?:\.\d{1,3})?'
        base:
          type: string
          pattern: '-?\d{1,3}(?:\.\d{1,3})?'
    # ---------
  # ---- Responses - Standard Errors Common Data Model v1.2.2----
  responses:
    standard400:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error as malformed request syntax.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard401:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json     
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard403:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Forbidden - The server understood the request but refuses to authorize it. 
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard404:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Not Found - The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard405:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Method Not Allowed - The method received in the request-line is known by the origin server but not supported by the target resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard500:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard501:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Not Implemented - The server does not support the functionality required to fulfill the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard503:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Service Unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
  # ---- End Responses - Standard Errors