openapi: "3.0.0"
info:
  version: 2.4.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: https://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)
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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/linksPagination'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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: Uuid v4 of a specific existing mortgage
          required: true
          example: bcb5d762-8d28-43a2-9398-393b2e8d56ba
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: Mortgage details with the corresponding properties and related mortgages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Mortgage:
                    $ref: '#/components/schemas/Mortgage'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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: duration
          schema:
            type: integer
            minimum: 1
            maximum: 20
          example: 10
          description: The type of duration (for filtering)
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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/linksPagination'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          required: true
          example: a86dd383-055e-471a-a098-682ae5ef8348
          description: A product's uuid v4
        - in: query
          name: duration
          schema:
            type: string
          description: The duration (for filtering)
        - in: query
          name: interest
          schema:
            type: string
          description: The interest (for filtering)
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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'
      parameters:
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '201':
          description: created
          headers:
            location:
              schema:
                type: string
                format: uri
                description: In the location header of the response you will find the URI of the newly created resource. With a GET call to this address you can retrieve a representation of the new product.
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
      parameters:
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyObject'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          required: true
          example: 4bf92636-14a0-4511-98e2-acfde576e644
          description: Uuid v4 of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  application:
                    $ref: '#/components/schemas/Application'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          required: true
          example: 7f810bcd-e430-4f52-8cdf-ddf7bfbd2903
          description: Uuid v4 of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          required: true
          example: 25cce7b2-ffb8-4800-88b0-e255ab75a829
          description: Uuid v4 of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          required: true
          example: a5f2cc2a-e2bf-45f0-a892-bc61dfb5fe02
          description: Uuid v4 of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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: In the location header of the response you will find the URI of the newly created resource. With a GET call to this address you can retrieve a representation of the new product.
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          example: 4a9aabc4-b893-4f16-a4f4-421a414ea628
          required: true
          description: Uuid v4 of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: string
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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: 83ad0ba5-d6d1-42d3-ba8d-5ea514799632
          description: Uuid v4 of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          required: true
          example: 7f648f12-c15f-4930-8380-238da5671c37
          description: Unique ID (uuid v4) of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      requestBody:
        description: Details of the document to be added
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - documentType
                - fileContent
                - name
                - type
                - size
              properties:
                documentType:
                  $ref: '#/components/schemas/DocumentType'
                fileContent:
                  type: string
                  format: binary
                  description: 'The file content.'
                name:
                  type: string
                  description: 'The name of the file without file type extension.'
                  maxLength: 128
                  example: 'my-property-flyer'
                type:
                  type: string
                  description: 'The file type.'
                  maxLength: 64
                  example: 'application/pdf'
                size:
                  type: integer
                  format: int64
                  description: 'The file size in bytes.'
                  example: '21543'
                applicantId:
                  type: string
                  format: uuid
                  description: UUID v4 of the applicant (existing applicant within the current application)
                  example: 576f8de3-6b30-4882-a7af-da2132a456cf
      responses:
        '201':
          description: created
          headers:
            documentId:
              schema:
                type: string
                format: uuid
                description: Uuid v4 of the created document defined by FI
                example: 232af5ca-fca3-4bd4-b91d-23d755d9af0f
            location:
              schema:
                type: string
                format: uri
                description: In the location header of the response you will find the URI of the newly created resource. With a GET call to this address you can retrieve a representation of the new product.
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          example: 7f648f12-fd45-4930-6543-456hf5671c37
          required: true
          description: Uuid v4 of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    filename:
                      type: string
                    filetype:
                      type: string
                    documentId:
                      type: string
                      format: uuid
                      description: Document ID in uuid v4 format
                    filesize:
                      type: integer
                    uploaddate:
                      $ref: '#/components/schemas/Date'
                    statusInfo:
                      description: 'Document status info'
                      type: object
                      required:
                        - status
                      properties:
                        status:
                          type: string
                          enum:
                            - accepted
                            - rejected
                            - pending
                        statusReason:
                          type: string
                          description: 'The reason, of current status.'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          example: 7f648f12-fd45-4930-6543-456hf5671c37
          required: true
          description: Uuid v4 of the application (dossier)
        - in: path
          name: documentId
          schema:
            type: string
            format: uuid
          example: 7f648f12-c15f-4930-8380-238da5671c37
          required: true
          description: Unique ID (uuid v4) of the document
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          example: 225f92e7-095f-4e06-a036-d3b5947c7e71
          required: true
          description: Uuid v4 of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          example: 7598b91b-c500-46c3-a196-0ab1610e692c
          required: true
          description: Uuid v4 of the application request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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: In the location header of the response you will find the URI of the newly created resource. With a GET call to this address you can retrieve a representation of the new product.
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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}/required-information:
    get:
      summary: List all required documents / information for processing specific Financial request at FI
      description: List all required documents / information for processing specific Financial request at FI
        This can be used when NO offer is available from FI
      tags:
        - Mortgage Financing Request
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
            format: uuid
          example: 1a75e7fc-f3c3-99a9-9268-ec21c405bbc8
          required: true
          description: Uuid v4 of the application request
        - in: path
          name: financingRequestId
          schema:
            type: string
            format: uuid
          example: 1a75e7fc-f3c3-45a9-9268-ec21c405bbc8
          required: true
          description: Uuid v4 of the financing request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  financingRequestId:
                    type: string
                    format: uuid
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentType'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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}:
    get:
      summary: Get the details of a financing request
      description: Get a specific financing request based on the financingRequestId
      tags:
        - Mortgage Financing Request
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
            format: uuid
          example: 78d01ce4-a01b-46dd-8d17-5f022d4f98h3
          required: true
          description: Uuid ID of the application
        - in: path
          name: financingRequestId
          schema:
            type: string
            format: uuid
          example: 78d01ce4-a01b-46dd-8d17-5f022d4f46f2
          required: true
          description: Uuid ID of the financing request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  offerList:
                    type: array
                    items:
                      $ref: '#/components/schemas/FinancingRequest'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          example: f005bcab-051f-437c-a010-242aa0390add
          required: true
          description: Uuid v4 of the application request
        - in: path
          name: financingRequestId
          schema:
            type: string
            format: uuid
          example: c0c6bcf8-4be7-4c3f-8e5e-cbec6ee95d95
          required: true
          description: Uuid v4 of the financing request
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  offerList:
                    type: array
                    items:
                      $ref: '#/components/schemas/Offer'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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: Uuid v4 of the application request
        - in: path
          name: financingRequestId
          schema:
            type: string
            format: uuid
          example: 1a75e7fc-f3c3-45a9-9268-ec21c405bbc8
          required: true
          description: Uuid v4 of the financing request
        - in: path
          name: offerId
          schema:
            type: string
            format: uuid
          example: c2fee261-053c-4088-8986-11216f0c9be6
          required: true
          description: Uuid v4 of the offer
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  offer:
                    $ref: '#/components/schemas/Offer'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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/offers/{offerId}/document:
    get:
      summary: Get document for the given offer
      description: Get document for the offer, this can be used by TPP to display offer content
      tags:
        - Mortgage Offers
      parameters:
        - in: path
          name: offerId
          schema:
            type: string
            format: uuid
          example: 8109fc33-8af0-4072-98aa-a7d0c5c896a7
          required: true
          description: Uuid v4 of an offer
        - in: query
          name: language
          schema:
            type: string
            enum:
              - de
              - fr
              - it
              - en
          description: 'Language of Document content'
          example: fr
          required: true
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  document:
                    $ref: '#/components/schemas/Document'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.

        '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}/required-information:
    get:
      summary: List all required documents / information for processing specific offer at FI
      description: List all required documents / information for processing specific offer at FI
      tags:
        - Mortgage Offers
      parameters:
        - in: path
          name: applicationId
          schema:
            type: string
            format: uuid
          example: 1a75e7fc-f3c3-99a9-9268-ec21c405bbc8
          required: true
          description: Uuid v4 of the application request
        - in: path
          name: financingRequestId
          schema:
            type: string
            format: uuid
          example: 1a75e7fc-f3c3-45a9-9268-ec21c405bbc8
          required: true
          description: Uuid v4 of the financing request
        - in: path
          name: offerId
          schema:
            type: string
            format: uuid
          example: c2fee261-053c-4088-8986-11216f0c9be6
          required: true
          description: Uuid v4 of the offer
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  offerId:
                    type: string
                    format: uuid
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentType'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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'
      parameters:
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '201':
          description: created
          headers:
            location:
              schema:
                type: string
                format: uri
                description: In the location header of the response you will find the URI of the newly created resource. With a GET call to this address you can retrieve a representation of the new product.
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          example: 91d029b3-ee7a-44c3-ac18-cf621cb128a8
          required: true
          description: Uuid v4 of an order
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  offer:
                    $ref: '#/components/schemas/Order'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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
            format: uuid
          example: 8109fc33-8af0-4072-98aa-a7d0c5c896a7
          required: true
          description: Uuid v4 of an order
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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}/document:
    get:
      summary: Get document for the given order
      description: Get document for given order, this can be used by TPP to display offer content
      tags:
        - Mortgage Order
      parameters:
        - in: path
          name: orderId
          schema:
            type: string
            format: uuid
          example: 8109fc33-8af0-4072-98aa-a7d0c5c896a7
          required: true
          description: Uuid v4 of an order
        - in: query
          name: language
          schema:
            type: string
            enum:
              - de
              - fr
              - it
              - en
          description: 'Language of Document content'
          example: fr
          required: true

        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  document:
                    $ref: '#/components/schemas/Document'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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: Uuid v4 of a specific expiring mortgage
          required: true
          example: 82d2f030-e840-40ea-9bc8-8b6cbc15f7bb
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      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'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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: Uuid v4 of a specific expiring mortgage
          example: 718934bb-aa8a-4917-a431-b64b844cacc3
          required: true
          schema:
            type: string
            format: uuid
        - name: offerId
          in: path
          description: Uuid v4 of a specific mortgage prolongation offer
          example: 46eb482d-1e18-4b93-ae88-da14ad4ac051
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
      responses:
        '200':
          description: Specific offer for a specific expiring mortgage
          content:
            application/json:
              schema:
                type: object
                properties:
                  offer:
                    $ref: '#/components/schemas/Offer'
          headers:
            X-Correlation-ID:
              schema:
                type: string
              description: Reflects the ID (set by the caller) from the request.
        '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 for Pagination----
    linksPagination:
      description: Links (or cursors) returned in the answer of an API call.
      type: object
      properties:
        self:
          type: string
          description: Link / cursor to the current result set (based on the submitted pagination approach)
          example: /mortgage-app/api/v1/products?offset=75&limit=25
        first:
          type: string
          description: Link / cursor to the first result set (based on the submitted pagination approach)
          example: /mortgage-app/api/v1/products?offset=0&limit=25
        previous:
          type: string
          description: Link / cursor to the previous result set (based on the submitted pagination approach)
          example: /mortgage-app/api/v1/products?offset=50&limit=25
        next:
          type: string
          description: Link / cursor to the next result set (based on the submitted pagination approach)
          example: /mortgage-app/api/v1/products?offset=100&limit=25
        last:
          type: string
          description: Link / cursor to the last result set (based on the submitted pagination approach)
          example: /mortgage-app/api/v1/products?offset=150&limit=25
    # ---------
    # ---- 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"
    # -----------
    # ---- Country Code ----
    Country:
      type: string
      pattern: '[A-Z]{2}'
      example: CH
      description: 2-Letter ISO 3166-2 Country Code
    # ------------
    # ---- Error Response
    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
        - address
      properties:
        propertyObjectId:
          type: string
          format: uuid
          description: 'The property object identifier (UUID v4) defined by TPP.'
          example: '9343dd26-4b54-4808-8978-538f8e869d0e'
        name:
          type: string
          description: User-defined property name
          example: My Nice Property
        address:
          $ref: '#/components/schemas/structuredAddress'
        propertyIdentifier:
          $ref: '#/components/schemas/PropertyIdentifier'
        propertyConstructionInformation:
          type: object
          description: 'The property construction information.'
          properties:
            constructionYear:
              type: integer
              description: 'construction year'
              example: 1990
            renovation:
              type: boolean
              description: 'If the property is renovated true, else false.'
              example: false
            renovationYear:
              type: integer
              description: 'renovation year'
              example: 1990
              default: 0
            minergieStandardType:
              type: string
              enum: [none, minergie, minergie-p, minergie-eco, minergie-p-eco]
              description: 'The minergie standard'
              example: 'minergie-p'
            constructionQualityType:
              $ref: '#/components/schemas/PropertyObjectRatingType'
            stateBuildingType:
              $ref: '#/components/schemas/PropertyObjectRatingType'
        classOfProperty:
          type: string
          enum: [main_residence, main_residence_with_use_restriction, second_residence, second_residence_with_use_restriction, rented_property, rented_property_with_use_restriction, other]
          description: 'The class of property (Main residence, second residence, rented).'
          example: 'main_residence'
        ceilingHight:
          type: string
          enum: [especially_high, middle, especially_low]
          description: 'The ceiling hight in the rooms.'
          example: 'middle'
        buildingStandardFloorCoverings:
          type: string
          enum: [premium, highlevel, basic, lowlevel]
          description: 'Building standard of the floor coverings.'
          example: 'basic'
        buildingStandardKitchen:
          type: string
          enum: [premium, highlevel, basic, lowlevel]
          description: 'Building standard of the kitchen.'
          example: 'basic'
        buildingStandardBathroom:
          type: string
          enum: [premium, highlevel, basic, lowlevel]
          description: 'Building standard of the sanitary installations.'
          example: 'basic'
        outsideConstructionZone:
          type: boolean
          description: 'If the property is outside of the construction zone.'
          example: false
        propertyElements:
          type: object
          description: 'The property detail information such as rooms count, parking places.'
          properties:
            numberOfRooms:
              type: number
              format: double
              description: 'The number of the rooms.'
              example: 4.5
            roomCountType:
              type: string
              enum: [kitchen_not_counted, kitchen_half_room, kitchen_full_room]
              description: 'Reflects the type of the room count type. E.g. if the kitchen counts as full room.'
              example: kitchen_full_room
            numberOfFamilyBathrooms:
              type: integer
              description: 'Separate shower and bathtub in the bathroom (optional: toilet)'
              example: 2
            numberOfBathWC:
              type: integer
              description: 'Bath or shower, sink, toilet'
              example: 2
            numberOfGuestWC:
              type: integer
              description: 'Separate, single toilet with wash basin'
              example: 2
            numberOfExternalParking:
              type: integer
              description: 'The number of external parking spaces.'
              example: 2
            numberOfSeparateGarages:
              type: integer
              description: 'The number of separated garages (covered parking spaces).'
              example: 2
            numberOfUndergroundCarParks:
              type: integer
              description: 'The number of underground parking places.'
              example: 2
        propertyFlatInformation:
          type: object
          description: 'The property flat information.'
          properties:
            numberOfFlats:
              type: integer
              description: 'The number of flats in the building.'
              example: 10
            numberOfFloors:
              type: integer
              description: 'The number of floors in the building.'
              example: 4
            stateApartmentType:
              $ref: '#/components/schemas/PropertyObjectRatingType'
            floor:
              type: integer
              description: 'The floor of the flat.'
              example: 2
            balconyOrTerraceArea:
              type: integer
              description: 'The area of the balcony or terrace in quatermeter.'
              example: 20
            livingSpace:
              type: object
              properties:
                livingSpaceInSqm:
                  type: integer
                  description: 'The area of the living space in quatermeter.'
                  example: 120
                measurementStandard:
                  type: string
                  enum: [nla, gfa]
                  description: 'The measurement standard used to determine the living space (nla or gfa).'
                  example: 'nla'
            multistorey:
              type: boolean
              description: 'If the flat is multistorey true, else false.'
              example: false
            otherFeatures:
              type: array
              items:
                type: string
                enum: [coowned_garden_terrace_room, coowned_indoor_pool, coowned_outdoor_pool, whirlpool_sauna, heated_conservatory, unheated_conservatory, security_system, chimney, elevator_in_stairwell, elevator_into_apartment, ventilation_system_without_mingergie, barrier-free_living, automated_building_control]
                description: 'Additional features and services.'
                example: 'coowned_outdoor_pool'
            quote:
              type: integer
              description: 'The quote of the flat property against the whole building property.'
              example: 120
            apartmentType:
              type: string
              enum: [garden_flat, floor_flat, roof_flat, attic]
              description: 'The type of the appartment (floor, garden level, storey).'
              example: 'floor_flat'
            buildingType:
              type: string
              enum: [multiple_family_house, terrace_house]
              description: 'The type of the building (multiple_family_house, terrace_house).'
              example: 'multiple_family_house'
            locationInTheBuildingRating:
              $ref: '#/components/schemas/PropertyObjectRatingType'
        propertyBuildingInformation:
          type: object
          description: 'The property building information.'
          properties:
            livingSpace:
              type: object
              properties:
                livingSpaceInSqm:
                  type: integer
                  description: 'The area of the living space in quatermeter.'
                  example: 120
                measurementStandard:
                  type: string
                  enum: [nla, gfa]
                  description: 'The measurement standard used to determine the living space (nla or gfa).'
                  example: 'nla'
            roofFloorExpandable:
              type: boolean
              description: 'If the roof floor is expandable true, else false.'
              example: false
            volumeIncludingGarage:
              type: integer
              description: 'The volume of the house including the garage.'
              example: 1500
            landArea:
              type: integer
              description: 'The surface area of the land.'
              example: 2000
            otherFeatures:
              type: array
              items:
                type: string
                enum: [ventilation_system_without_mingergie, barrier-free_living, automated_building_control]
                description: 'Additional features and services.'
                example: 'outdoor_pool'
            houseType:
              type: string
              enum: [detached_house, semidetached_house, row_house, row_corner_house, terrace_house]
              description: 'The type of the house.'
              example: 'detached_house'
            normType:
              type: string
              enum: [building_insurance, sia116, sia416, other]
              description: 'The norm type.'
              example: 'building_insurance'
        valueRelevantServitudes:
          type: boolean
          description: 'If the property has servitudes true, else false.'
          example: false
        buildingRight:
          type: object
          properties:
            hasBuildingRight:
              type: boolean
              description: 'If the property is built in a building right true, else false.'
              example: false
            buildingRightExpiry:
              $ref: '#/components/schemas/Date'
              description: 'Date when the building right expires.'
            buildingRightRent:
              $ref: '#/components/schemas/Amount'
              description: 'Yearly payment for the building right.'
            buildingRightCompensation:
              $ref: '#/components/schemas/Amount'
              description: 'Payment received at the building right expiry.'
        objectPrice:
          $ref: '#/components/schemas/Amount'
        estimation:
          type: object
          properties:
            estimationSourceType:
              type: string
              example: iazi
              enum:
                - iazi
                - wup
            amount:
              $ref: '#/components/schemas/Amount'
            estimationDate:
              $ref: '#/components/schemas/Date'
        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
      properties:
        mortgageId:
          type: string
          format: uuid
          example: 206065b9-977b-4d2c-9092-00acf2392346
          description: Uuid v4 of the specific mortgage
        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'
    # ---------

    # ---- Mortgage Offer ----
    Offer:
      description: All relevant details describing the FI's offer for a mortgage product
      type: object
      required:
        - offerId
        - financingRequestId
        - totalAmount
        - validTo
        - offerItems
      properties:
        offerId:
          type: string
          format: uuid
          example: 46eb482d-1e18-4b93-ae88-da14ad4ac051
          description: Uuid v4 of the specific order
        financingRequestId:
          type: string
          format: uuid
          example: fd3f2940-c9c9-46e7-8ed6-ab9e90363b2e
          description: Uuid v4 of a specific financing request
        totalAmount:
          $ref: '#/components/schemas/Amount'
        validTo:
          $ref: '#/components/schemas/Date'
        offerItems:
          type: array
          items:
            $ref: '#/components/schemas/OfferItem'
        offerType:
          type: string
          enum:
            - binding
            - indicative

    # ---------

    # ---- 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
        - trancheId
      properties:
        trancheId:
          type: string
          format: uuid
          description: Uuid of the tranche
          example: 51b017e1-5e59-4b58-a0a0-c638c87db463
        offerItemId:
          type: string
          format: uuid
          example: d452083f-8316-410d-a609-d49463687329
          description: Uuid v4 of the specific offer item
        product:
          $ref: '#/components/schemas/Product'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/Condition'
    # ---------

    # ---- Mortgage Product Variation
    ProductVariation:
      description: Product variation details
      type: object
      properties:
        duration:
          type: integer
          format: int32
          description: 'The duration in years.'
          minimum: 1
          maximum: 20
          example: 5
        rate:
          type: number
          format: double
          description: 'The interest rate.'
          minimum: 0
          maximum: 1
          example: 0.5
        saronperiod:
          type: string
          description: 'The saron period.'
          example: 3m
          enum:
            - 1m
            - 3m
            - 6m
            - 12m
    # ---------

    # ---- Mortgage Product ----
    Product:
      description: All details regarding an FI's mortgage product
      type: object
      required:
        - productId
        - names
        - interestRateType
      properties:
        productId:
          type: string
          format: uuid
          description: 'The product identifier (UUID v4).'
          example: '20460121-6aff-485b-a61d-6056ecd72bd8'
        names:
          type: array
          items:
            type: object
            properties:
              description:
                type: string
                description: 'Product name description'
                example: "Fixed rate mortgage"
              language:
                type: string
                description: 'Language of product name'
                example: fr
                enum:
                  - de
                  - fr
                  - it
                  - en
        productVariations:
          type: array
          items:
            $ref: '#/components/schemas/ProductVariation'
        interestRateType:
          type: string
          example: libor
          enum:
            - variable
            - libor
            - saron
            - fixed
        # ---------

    # ---- 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
          format: uuid
          example: ef737eb0-c0a7-4f44-bdeb-32ba9bd99327
        productIdRef:
          type: string
          format: uuid
          example: 0b34cd1b-32a5-4bb7-bcc5-bf81f8f8aaf1
        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:
        primaryApplicantId:
          type: string
          format: uuid
          description: ApplicantId for primary applicant of the applicant party. In case of multiple applicants this field is mandatory.
          example: 576f8de3-6b30-4882-a7af-da2132a456cf
        personList:
          type: array
          items:
            $ref: '#/components/schemas/Applicant'
    # ---------

    # ---- Application ----
    Application:
      description: All static application information needed by the FI to create binding offers
      type: object
      required:
        - mortgageType
        - requestingParty
        - propertyInformation
      properties:
        applicationId:
          type: string
          format: uuid
          description: 'The application identifier (UUID v4) defined by FI.'
          example: 'f157c4be-106d-4304-972e-091e77b87e1c'
        tppApplicationId:
          type: string
          description: 'The application alphanumeric identifier defined by TPP'
          pattern: '^[a-zA-Z0-9]{6,10}$'
          example: 'asd23f'
        requestingParty:
          $ref: '#/components/schemas/Party'
        propertyInformation:
          $ref: '#/components/schemas/PropertyObject'
        mortgageType:
          type: string
          description: 'Type of business, Values: buy, replacement.'
          example: buy
          enum:
            - buy
            - replacement
        replacementType:
          type: string
          description: 'NOT required when mortgage type is BUY, Values: entire, partial.'
          example: 'entire'
          enum:
            - entire
            - partial
        tppAdvisorDetail:
          type: object
          properties:
            name:
              type: string
              maxLength: 70
              description: Name of the TPP advisor
              example: Muster
            surName:
              type: string
              maxLength: 70
              description: Surname of the TPP advisor
              example: Max
            email:
              type: string
              description: Email of the TPP advisor
              example: max.muster@domain.ch
            language:
              type: string
              example: fr
              description: Preferred contact language of the applicant
              enum:
                - de
                - fr
                - it
                - en
            phone:
              type: string
              description: phone of the TPP advisor
              example: '+41443343456'
            address:
              $ref: '#/components/schemas/structuredAddress'

    # ---------

    # ---- Financing Request ----
    FinancingRequest:
      description: Based on the application, several financing requests can be sent to the FI
      type: object
      required:
        - applicationId
        - amount
      properties:
        financingRequestId:
          type: string
          format: uuid
          example: 2e1d21c3-0cd5-4354-a9e9-d2eb2c28b780
          description: Uuid v4 of the financing request defined by FI
        applicationId:
          type: string
          format: uuid
          example: 3c921870-f29c-46ad-9ba5-c8b05e0d88d2
          description: Uuid v4 of the corresponding application
        amount:
          $ref: '#/components/schemas/Amount'
        tranches:
          type: array
          items:
            type: object
            properties:
              trancheId:
                type: string
                format: uuid
                description: Uuid of the tranche
                example: 51b017e1-5e59-4b58-a0a0-c638c87db463
              productId:
                type: string
                format: uuid
                description: Uuid of the product
                example: 6e61ff5d-3ffd-4254-a77d-73cc25d35e92
              productVariation:
                $ref: '#/components/schemas/ProductVariation'
              payOutDate:
                $ref: '#/components/schemas/Date'
              amount:
                $ref: '#/components/schemas/Amount'
        usedAssets:
          type: array
          items:
            $ref: '#/components/schemas/UsedAsset'
        publicCertDate:
          $ref: '#/components/schemas/Date'
    # ---------

    # ---- Applicant ----
    Applicant:
      description: Applicant information needed by the FI for creating a binding offer.
      type: object
      required:
        - applicantId
        - applicantType
        - applicantDetail
      properties:
        applicantId:
          type: string
          format: uuid
          description: UUID v4 of the applicant (to be defined by TPP)
          example: 576f8de3-6b30-4882-a7af-da2132a456cf
        applicantType:
          type: string
          example: individual
          enum:
            - individual
            - legal_entity
        applicantDetail:
          type: object
          properties:
            name:
              type: string
              maxLength: 70
              description: Name of the applicant
              example: Muster
            surName:
              type: string
              maxLength: 70
              description: Surname of the applicant
              example: Max
            address:
              $ref: '#/components/schemas/structuredAddress'
            birthDate:
              $ref: '#/components/schemas/Date'
            maritalStatus:
              type: string
              example: married
              description: Martial status of the applicant
              enum:
                - unmarried
                - married
                - divorced
                - widowed
                - registered-partnership
            matrimonialPropertyScheme:
              type: string
              example: separateEstate
              enum:
                - jointEstate
                - separateEstate
                - contributionToJointlyAcquiredProperty
            jobSituation:
              type: string
              example: employed
              description: Job situation of the applicant
              enum:
                - employed
                - selfEmployed
                - unemployed
                - retired
            nationality:
              $ref: '#/components/schemas/Country'
            USPerson:
              type: boolean
              description: Is the applicant a US person?
              example: false
            email:
              type: string
              description: Email of the applicant
              example: max.muster@domain.ch
            applicantLanguage:
              type: string
              example: fr
              description: Preferred contact language of the applicant
              enum:
                - de
                - fr
                - it
                - en
            gender:
              type: string
              enum:
                - male
                - female
                - other
              example: female
              description: Gender of the applicant.
        financialSituation:
          type: object
          properties:
            income:
              type: array
              items:
                type: object
                properties:
                  incomeType:
                    $ref: '#/components/schemas/IncomeType'
                  amount:
                    $ref: '#/components/schemas/Amount'
                  remark:
                    type: string
            liabilities:
              type: array
              items:
                type: object
                properties:
                  liabilityType:
                    type: string
                    example: mortgage
                    description: Liability type
                    enum:
                      - leasing
                      - alimony
                      - mortgage
                      - other
                  amount:
                    $ref: '#/components/schemas/Amount'
                  remark:
                    type: string
            assets:
              type: array
              items:
                $ref: '#/components/schemas/Asset'
    # ---------

    # ---- Mortgage data types ----
    PropertyObjectRatingType:
      type: string
      enum: [bad, bad-medium, medium, medium-good, good, good-verygood, verygood]
      description: 'The rating type.'
      example: 'good'
    CommonID:
      description: "The unique identifier UUID v4 specified by RFC4122."
      type: string
      format: uuid
      example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
    AssetType:
      description: Common set of asset types.
      type: string
      example: cash
      enum:
        - cash
        - gift
        - reservation_deposit
        - advancement_of_inheritance
        - third_pillar
        - pension_fund
        - third_party_loan
        - third_pillar_fund
        - fungible_investments
        - other
        - vested_benefit
        - life_insurance_3a
        - life_insurance_3b
    AssetUsageType:
      description: Common set of asset usage types.
      type: string
      example: pledged
      enum:
        - pledged
        - withdraw
    Asset:
      description: Asset information.
      type: object
      required:
        - assetType
        - amount
      properties:
        assetType:
          $ref: '#/components/schemas/AssetType'
        amount:
          $ref: '#/components/schemas/Amount'
        remark:
          type: string
        assetProvider:
          $ref: '#/components/schemas/AssetProvider'
    UsedAsset:
      description: Asset used by an applicant.
      type: object
      required:
        - assetType
        - amount
        - applicantId
      properties:
        assetType:
          $ref: '#/components/schemas/AssetType'
        amount:
          $ref: '#/components/schemas/Amount'
        usageType:
          $ref: '#/components/schemas/AssetUsageType'
        applicantId:
          type: string
          format: uuid
          description: UUID v4 of the applicant (existing applicant within the current application)
          example: 576f8de3-6b30-4882-a7af-da2132a456cf
        assetProvider:
          $ref: '#/components/schemas/AssetProvider'
    IncomeType:
      description: Common set of income types.
        For the enum value self_employment and dividend the 3 years avg is relevant.
      type: string
      example: employment_gross
      enum:
        - employment_gross
        - employment_net
        - self_employment
        - self_employment_year-1
        - self_employment_year-2
        - self_employment_year-3
        - bonus_year-1
        - bonus_year-2
        - bonus_year-3
        - additional_income
        - child_allowance
        - asset_consumption_before_retirement
        - pension_fund_income
        - ahv_income
        - further_income_after_retirement
        - asset_consumption_after_retirement
        - fixed_expenses
        - dividend
    DocumentType:
      description: All supported document types.
        For the enum value tax_statement. Tax statement is required.
      type: string
      example: tax_statement
      enum:
        - cash
        - gift
        - reservation_deposit
        - advancement_of_inheritance
        - third_pillar
        - pension_fund
        - third_party_loan
        - third_pillar_fund
        - fungible_investments
        - vested_benefit
        - life_insurance_3a
        - life_insurance_3b
        - tax_statement
        - lending_of_third_party_property
        - employment
        - self_employment
        - additional_income
        - pension_fund_income
        - ahv_income
        - fixed_expenses
        - dividend
        - publicly_notarized_purchase_contract
        - draft_purchase_contract
        - land_register_extract
        - official_estimation
        - building_insurance_certificate
        - professional_estimation
        - real_estate_documentation
        - situation_cadastral_plan
        - floor_plan
        - property_pictures_outside
        - property_pictures_inside
        - proof_of_interest
        - easements_contracts
        - owner_association
        - contract_for_the_establishment
        - mortgage_note
        - mortgage_note_erection
        - salary_certificate_month
        - salary_certificate_year
        - consent_form
        - debt_information
        - divorce_copy
        - building_plan
        - survey_copy
        - cubical_calculation
        - other
    # ---------

    # ---- Order ----
    Order:
      description: All information needed to choose a specific offer and place a binding order.
      type: object
      required:
        - offerId
      properties:
        orderId:
          type: string
          format: uuid
          example: 6faea0b8-26a2-4b17-b10f-8f56fe355f50
          description: Uuid v4 of the order defined by FI
        offerId:
          type: string
          format: uuid
          example: 2752ce81-5bf0-4991-89ac-87d6e7fd0c47
        mortgageId:
          type: string
          format: uuid
          example: ef25ce8b-2fb1-45d9-bae0-6f263241a280
        applicationId:
          type: string
          format: uuid
          example: 59e8c8a6-4d32-4e7b-bcf0-05813029498e
        validateOnly:
          type: boolean
          description: The order will not be persistent in the FI backend.
          example: true
        remark:
          type: string
          example: All documents verified at TPP
          description: Remark/comment which can be added by TPP

    # ---------

    # ---- Document ----
    Document:
      description: Document containing information for givent document type for given order.
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: MortgageOffer_WaimerANON_587b23d1-12a8-475a-968b-abee245e3393
          description: Name of the document
        parentId:
          type: string
          format: uuid
          example: 2752ce81-5bf0-4991-89ac-87d6e7fd0c47
          description: Id for parent object of given document
        content:
          type: string
          description: base64 Encoded Content
          example: JVBERi0xLjQKJeLjz9MKMzEgMCBvYmoKPDwvQnl0ZVJhbmdl
        contentType:
          type: string
          description: Content type
          example: application/octet-stream
        createDate:
          $ref: '#/components/schemas/Date'
        modifyDate:
          $ref: '#/components/schemas/Date'
    # ---------
    # ---- AssetProvider ----
    AssetProvider:
      description: Asset provider for each asset, additional information must be transfered. E.g. in case the applicant owns an addtional security of type insurance, insurance company name is provided
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: Credit Suisse
          description: Name of the asset provider
    # ---------

    # ---- 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: number
          format: double
          description: 'Interest reate in decimals. 2.45% would be sent as 0.0245. For flexible interest mortgage this would show the margin above interest.Base'
          minimum: 0
          maximum: 1
          example: 0.5
        base:
          type: number
          format: double
          description: 'Base rate uupon margin is applied (e.g. for SARON).'
          minimum: 0
          maximum: 1
          example: 0.5
    # ---------

  # ---- Global Common Header Parameters ----
  parameters:
    clientid_in_header:
      in: header
      name: X-CorAPI-Client-ID
      schema:
        type: string
      description: 'ID of the client forwarded to the provider. (SCOPE: FI)'
      required: true
    correlation_in_header:
      in: header
      name: X-Correlation-ID
      schema:
        type: string
      description: Unique ID (defined by the caller) which will be reflected back in the response.
      required: true
    agent_in_header:
      in: header
      name: User-Agent
      schema:
        type: string
      description: Name and version of the of the Client software
      required: true
    offset:
      name: offset
      in: query
      description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
      required: false
      schema:
        type: integer
        format: int32
        example: 25
        minimum: 0
    limit:
      name: limit
      in: query
      description: Optional parameter for pagination. Maximum number of entries to be returned.
      required: false
      schema:
        type: integer
        format: int32
        example: 25
        minimum: 1
    cursor:
      name: cursor
      in: query
      description: Optional parameter for pagination. An opaque string value used for pagination.
      required: false
      schema:
        type: string
        example: cursorIDxyz
  # ---- 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