openapi: 3.0.0 info: version: 3.6.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: Full Mortgage Cases description: Operatios related to full mortgage cases including the application details - 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: /mortgage-cases: get: tags: - Full Mortgage Cases summary: Return the list of all mortgage cases for the authenticated context description: List of mortgage cases for the authenticated context including the corresponding properties, sorted by caseId. parameters: - $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': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: Paginated list of all mortgage cases with all related information sorted by caseId. content: application/json: schema: type: object properties: caseList: type: array items: $ref: '#/components/schemas/MortgageCase' _links: $ref: '#/components/schemas/linksPagination' '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' /mortgage-cases/{caseId}: get: tags: - Full Mortgage Cases summary: Return a specific existing mortgage case description: A specific existing mortgage case including the corresponding properties. parameters: - $ref: '#/components/parameters/path_caseId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: Mortgage case details with the corresponding properties. content: application/json: schema: type: object properties: Case: $ref: '#/components/schemas/MortgageCase' '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: get: tags: - Existing Mortgages summary: Return the list of all mortgages for the authenticated context description: List of mortgages for the authenticated context including the corresponding properties and related mortgages, sorted by mortgageId. 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': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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' '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 summary: Return a specific existing mortgage description: A specific existing mortgage including the corresponding properties and related mortgages. parameters: - $ref: '#/components/parameters/path_mortgageId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: Mortgage details with the corresponding properties and related mortgages. content: application/json: schema: type: object properties: Mortgage: $ref: '#/components/schemas/Mortgage' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/products: get: summary: Get a list of all mortgage products description: Get a complete overview of all available mortgage products sorted by productId. tags: - Mortgage Products and Conditions parameters: - in: query name: interestRateType schema: type: string example: saron enum: - variable - libor - saron - fixed description: The type of the interest rates (for filtering). - $ref: '#/components/parameters/duration' - $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': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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' '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: - $ref: '#/components/parameters/path_productId' - $ref: '#/components/parameters/limit' - 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': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: List of conditions related to a specific mortgage product. content: application/json: schema: type: object properties: conditionList: type: array items: $ref: '#/components/schemas/Condition' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications: post: summary: Place a new mortgage application (serves as dossier) description: | Place a new application including all necessary information about the property and applicant's financial situation. **Note that in the case where the FI needs additional information on the property, the error response 400 must contain the minimum required JSON object (PropertyObject) as detail**. tags: - Mortgage Application parameters: - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' requestBody: description: Static details (requesting party, property object) of the application to be added as a dossier. required: true content: application/json: schema: $ref: '#/components/schemas/Application' responses: '201': $ref: '#/components/responses/standard201' '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': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: $ref: '#/components/schemas/PropertyObject' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}: get: summary: Get the details of a specific placed application description: Get the details of a specific placed application. tags: - Mortgage Application parameters: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: application: $ref: '#/components/schemas/Application' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' put: summary: Update the application's details description: Update the application's details. Note that changing the application's details should not be possible after the application has been accepted by the FI. tags: - Mortgage Application parameters: - $ref: '#/components/parameters/path_applicationId' - $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': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: status: type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' delete: summary: Cancel the application and removing it description: The request to delete a previously shared application. tags: - Mortgage Application parameters: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: reason: description: The reason for rejecting an application. type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/swissrets: post: summary: Add property details in the SwissRETS standard description: This endpoint allows to upload the real estate property's details as an XML file in the SwissRETS format according to https://swissrets.ch/. tags: - Mortgage Application parameters: - $ref: '#/components/parameters/path_applicationId' - $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': $ref: '#/components/responses/standard201' '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: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/xml: schema: type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' put: summary: Update the real estate property's details description: This endpoint allows to upload a modified XML file in the SwissRETS format changing the already existing information. tags: - Mortgage Application parameters: - $ref: '#/components/parameters/path_applicationId' - $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': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: status: type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/documents: post: summary: Add documents for the specific application description: Documents can be assigned to a specific application ID. tags: - Mortgage Application parameters: - $ref: '#/components/parameters/path_applicationId' - $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': $ref: '#/components/responses/standard201' '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: All documents that have been shared against the Application ID can be retrieved here. tags: - Mortgage Application parameters: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: array items: type: object properties: filename: type: string example: customer_id.pdf filetype: type: string example: pdf documentId: type: string format: uuid example: 7f648f12-fd45-4930-6543-456hf5671c37 description: Document ID in uuid v4 format. filesize: type: integer example: 1024 description: The file size in bytes. uploaddate: $ref: '#/components/schemas/Date' statusInfo: description: Document status info. type: object required: - status properties: status: type: string enum: - accepted - rejected - pending default: pending description: Get the current status of the application. statusReason: type: string example: Additional information that can be shared with the status. description: The reason, of current status. '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: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/path_documentId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: status: type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/status: get: summary: Get the current status of the application description: Get the current status of the application (rejected with reason, accepted, pending with reason). tags: - Mortgage Application parameters: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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 description: Additional information that can be shared with the status. '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: - $ref: '#/components/parameters/path_applicationId' - $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': $ref: '#/components/responses/standard201' '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: All required documents for a specific FinancingRequestId can be retrieved herewith. tags: - Mortgage Financing Request parameters: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/path_financingRequestId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK content: application/json: schema: type: object properties: financingRequestId: type: string format: uuid documents: type: array items: $ref: '#/components/schemas/DocumentType' '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: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/path_financingRequestId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: offerList: type: array items: $ref: '#/components/schemas/FinancingRequest' '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: Lists the offers for a transferred application and the corresponding financing request. tags: - Mortgage Offers parameters: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/path_financingRequestId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: offerList: type: array items: $ref: '#/components/schemas/Offer' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/financing-requests/{financingRequestId}/offers/{offerId}: get: summary: Get the details of a specific offer description: Get the details of a specific offer for a specific placed application. tags: - Mortgage Offers parameters: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/path_financingRequestId' - $ref: '#/components/parameters/path_offerId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: offer: $ref: '#/components/schemas/Offer' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/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: - $ref: '#/components/parameters/path_offerId' - $ref: '#/components/parameters/language' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: document: $ref: '#/components/schemas/Document' '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: > Lists the required documents for the previously submitted case. Thus, the TPP knows which documents are needed for the later check. tags: - Mortgage Offers parameters: - $ref: '#/components/parameters/path_applicationId' - $ref: '#/components/parameters/path_financingRequestId' - $ref: '#/components/parameters/path_offerId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: offerId: type: string format: uuid documents: type: array items: $ref: '#/components/schemas/DocumentType' '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 parameters: - $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/Order' responses: '201': $ref: '#/components/responses/standard201' '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: - $ref: '#/components/parameters/path_orderId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: offer: $ref: '#/components/schemas/Order' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/orders/{orderId}/status: get: summary: Get the current status of the order description: > Returns the current status of the order. An order can be in accepted rejected or pending status. In addition, further details regarding the status can be transferred. tags: - Mortgage Order parameters: - $ref: '#/components/parameters/path_orderId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: status: type: string enum: - accepted - rejected - pending example: pending detail: type: string example: Waiting for details '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/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: - $ref: '#/components/parameters/path_orderId' - $ref: '#/components/parameters/language' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: OK. content: application/json: schema: type: object properties: document: $ref: '#/components/schemas/Document' '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 summary: Get all active offers for a specific tranche description: Get offer framework for the to be extended mortgage. parameters: - $ref: '#/components/parameters/path_mortgageId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: Paginated list of all offers for a specific expiring mortgage. content: application/json: schema: type: object properties: offerList: type: array items: $ref: '#/components/schemas/Offer' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/{mortgageId}/offers/{offerId}: get: tags: - Mortgage Prolongation summary: Get a specific offer for a specific tranche description: Get a specific offer for the to be extended mortgage. parameters: - $ref: '#/components/parameters/path_mortgageId' - $ref: '#/components/parameters/path_offerId' - $ref: '#/components/parameters/clientid_in_header' - $ref: '#/components/parameters/correlation_in_header' - $ref: '#/components/parameters/agent_in_header' responses: '200': headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: Specific offer for a specific expiring mortgage. content: application/json: schema: type: object properties: offer: $ref: '#/components/schemas/Offer' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' # ------------------------- # -------- Models --------- # ------------------------- components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://example.com/oauth/token scopes: read: Grants read access write: Grants write access schemas: # ---- Common Data Model v1.2.0 # ---- Date Formats Date: type: string format: date example: 2018-04-13 DateTime: type: string format: date-time example: 2018-04-13T11:11:11Z # ---- Links 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 # ---- Response commonResourceCreatedResponse: title: Recource created response description: Uuid v4 of the created resource example: 20460121-6aff-485b-a61d-6056ecd72bd8 type: object required: - id properties: id: $ref: '#/components/schemas/CommonID' description: Uuid v4 of the created resource example: bcb5d762-8d28-43a2-9398-393b2e8d56ba 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: array items: type: string example: List of 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 Response # ---- End Common Data Model 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 description: The property object identifier 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 propertyRenovations: type: array items: type: object properties: refurbishmentComponentType: type: string enum: - total - interior_fittings_kitchen - interior_fittings_bathroom_sanitary - interior_fittings_floor_cover - interior_fittings_remaining - building_envelope_pitched_roof - building_envelope_flat_roof - building_services_heat_production - building_services_heat_emission - buildings_services_electrical_ventilation_elevator - work_on_surroundings - supporting_structure - building_envelope_windows - building_envelope_facade_balcony - interior_fittings - building_envelope - building_services description: Type of Property Component which has been renovated. Please use consistently either the detailed Component Types (e.g. interior_fittings_floor_cover) or the simple Component Types (e.g. interior_fittings) example: interior_fittings_floor_cover yearOfRenovation: type: integer description: renovation year example: 2015 default: 0 renovationCost: $ref: '#/components/schemas/Amount' description: cost of renovation minergieStandardType: type: string enum: - none - minergie - minergie-p - minergie-eco - minergie-p-eco - minergie-a - minergie-a-eco description: The minergie standard example: minergie-p BECCStandardType: type: string enum: - none - A - B - C - D - E - F - G description: Energy certificate from Cantons example: B luxusFlag: type: string enum: - 0 - 0.5 - 1.0 description: 'Used for object value calculation (e.g. IAZI) and indicates whether an object is luxury or not: 0 = No, 0.5 = Partially, 1 = Yes. Proposed Mapping of WuP-Values: 1.0-4.0 => 0 (No) / 4.1-4.5 => 0.5 (Partially) / 4.6-5.0 = >1.0 (Yes).' example: 0 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 floorPlan: type: string enum: - efficient - average - inefficient description: The efficiency of the floor plan example: average usageType: type: string enum: - self - let description: 'The type of usage of the financing property: self, let' example: self propertyType: type: string enum: - single_family_house - condominium - vacation_house - vacation_condominium - agricultural_farm - 2or3_family_house - multi_family_house - residential_building_plot - building_plot_other - mixed_property - commercial_condominium - office_building - industrial_building - special_object description: The type of property example: single_family_house 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 heatEmission: type: array items: type: string enum: - floor - radiator - stove - other description: Type of the heat emission example: floor heatProduction: type: array items: type: string enum: - oil - gas - biogas - wood - electric - geothermal_probe - heat_pump_water_water - heat_pump_air_water - district - district_fossil - solar_panel - solar_thermal_collector - block_type_thermal_power_station - block_type_thermal_power_station_bio description: Type of the heat production example: gas 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 numberOfRoomsInGrannyFlat: type: number format: double description: The number of the rooms in the granny flat example: 2.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 - barrier-free_living - automated_building_control - ventilation_system_without_minergie 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 apartment (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 volumeIncludingGarageInhouse: type: integer description: The volume of the house including the inhouse garage (relevant for WuP). example: 1500 volumeIncludingAllGarages: type: integer description: The volume of the house including all inhouse and external garages and garage boxes (relevant for IAZI). example: 1620 landArea: type: integer description: The surface area of the land. example: 2000 environmentStandard: type: string enum: - high-level - basic - low-level description: The rating type example: basic otherFeatures: type: array items: type: string enum: - barrier-free_living - automated_building_control - ventilation_system_without_minergie - indoor_pool - outdoor_pool - whirlpool_sauna - heated_conservatory - unheated_conservatory - security_system - chimney - passenger_elevator - freight_elevator 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' description: Price paid to buy the property renovationAmount: $ref: '#/components/schemas/Amount' description: Amount needed to pay the planned renovation (Renovationsbetrag) investmentCost: $ref: '#/components/schemas/Amount' description: Total amount needed to pay object price and planned renovation (Total Anlagekosten) collateralValue: $ref: '#/components/schemas/Amount' description: Value of the property as base for the securization applying the lowest value principle (Belehnungsbasis) limitForLandEncumbrances: $ref: '#/components/schemas/Amount' description: The limit for land encumbrance according to Bundesgericht über das bäuerliche Bodenrecht, SR 211.412.11 (Belastungsgrenze BGBB) estimation: type: object properties: estimationId: type: string description: ID of the property estimation to connect the done estimation in the core banking system with the estimation of the tpp in the external estimation tool. example: asd23f estimationSourceType: type: string example: iazi enum: - iazi - wup marketValue: $ref: '#/components/schemas/Amount' description: Estimated Market value of the property statisticalPriceRangeMax: $ref: '#/components/schemas/Amount' description: Estimated statistical price range maximum statisticalPriceRangeMin: $ref: '#/components/schemas/Amount' description: Estimated statistical price range minimum yearlyRentalIncome: $ref: '#/components/schemas/Amount' description: Estimated rental income per year estimationDate: $ref: '#/components/schemas/Date' transferOfOwnershipDate: $ref: '#/components/schemas/Date' description: When the property will be fully transfered to the new owner publicNotarization: $ref: '#/components/schemas/Date' description: Date of public notarization remarks: type: string propertyLinks: description: A list of links to external resources related to the property type: array items: $ref: '#/components/schemas/Link' PropertyIdentifier: description: Property identification (register of real estate) type: object properties: EGRID: type: string EGID: type: string 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' offerDate: $ref: '#/components/schemas/Date' description: The date when the offer is made by the FI. Optional field for use cases where no MortageOffer object is used and therefore the offer date needs to be directly in Mortgage object. example: 2018-04-05 validTo: $ref: '#/components/schemas/Date' interestRate: type: string interestRateType: type: string example: libor enum: - variable - libor - saron - fixed interestBasis: type: string durationType: type: integer description: The duration in years. minimum: 0 maximum: 25 example: 5 prolongable: type: boolean propertyObjects: type: array items: $ref: '#/components/schemas/PropertyObject' relatedMortgages: type: array items: $ref: '#/components/schemas/Mortgage' 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 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' ProductVariation: description: Product variation details type: object properties: duration: type: integer description: The duration in years. minimum: 0 maximum: 25 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 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 Condition: description: All details regarding the conditions for a specific mortgage product the FI offers type: object required: - conditionId - productIdRef - duration - maturityDate - interest - amountRange - amortization 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: integer description: The duration in years. minimum: 0 maximum: 25 example: 5 maturityDate: $ref: '#/components/schemas/Date' interest: $ref: '#/components/schemas/Interest' amountRange: $ref: '#/components/schemas/AmountRange' amortization: type: integer amortizations: $ref: '#/components/schemas/Amortizations' 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 fiPrimaryApplicantId: type: string description: ApplicantId for primary applicant of the applicant party defined by the financial institute, only applicable in case of multiple applicants and if known at the moment of the application. example: asd23f personList: type: array items: $ref: '#/components/schemas/Applicant' 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. example: buy enum: - buy - replacement - construction_financing channelType: type: string enum: - advisor - direct description: The type of the channel the application was generated example: advisor replacementType: type: string description: 'NOT required when mortgage type is BUY, Values: entire, partial.' example: entire enum: - entire - partial replacedTranches: type: array items: type: object properties: replacedTrancheAmount: $ref: '#/components/schemas/Amount' description: The amount of the replaced tranche replacedTrancheExpiry: $ref: '#/components/schemas/Date' description: The expiry date of the replaced tranche example: 2022-05-03 replacedTrancheIssuer: type: string description: The institute who has issued the replaced tranche example: Credit Suisse tppAdvisorDetail: type: object properties: name: type: string maxLength: 70 description: Name of the TPP advisor example: Max surName: type: string maxLength: 70 description: Surname of the TPP advisor example: Muster nameTpp: type: string maxLength: 70 description: Firm of the TPP advisor example: Muster Finanz AG 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 TPP advisor enum: - de - fr - it - en phone: type: string description: phone of the TPP advisor example: '+41443343456' address: $ref: '#/components/schemas/structuredAddress' Advertiser: description: Information about the person or agency selling the property, in case it is applicable and known type: object required: - name properties: advertiserType: description: Specifies if the advertiser is a private person, a company or an agency type: string enum: - private - company - agency example: agency name: description: The name of the advertiser type: string maxLength: 140 example: Real Estate Agency AG contactPerson: description: The person to contact in case the advertiser is an agency or a company type: string maxLength: 140 example: Max Muster language: description: Preferred contact language of the advertiser type: string example: fr enum: - de - fr - it - en phone: description: The number on which the advertiser can be reached type: string minLength: 4 maxLength: 13 example: +41443343456 email: description: The email address on which the advertiser can be contacted type: string format: email minLength: 5 example: max.muster@domain.ch address: $ref: '#/components/schemas/structuredAddress' MortgageCase: description: A complete mortgage case including the application details type: object required: - caseId - application - financing properties: caseId: type: string format: uuid example: 2e1d21c3-0cd5-4354-a9e9-d2eb2c28b780 description: Uuid v4 of the mortgage case application: $ref: '#/components/schemas/Application' financing: $ref: '#/components/schemas/Financing' remark: type: string example: All documents verified at TPP description: Remark/comment which can be added by TPP Financing: description: Complete financing details of an application type: object required: - amount properties: financingId: type: string format: uuid description: Uuid of the financing example: 6e61ff5d-3ffd-4254-a77d-73cc25d35e92 applicationIdRef: type: string format: uuid description: Uuid of the financing's corresponding application example: 6e61ff5d-3ffd-4254-a77d-73cc25d35e92 amount: $ref: '#/components/schemas/Amount' increaseAmount: $ref: '#/components/schemas/Amount' increasePurpose: type: string description: The purpose of the increase. example: renovation of the kitchen amortizations: $ref: '#/components/schemas/Amortizations' tranches: type: array items: $ref: '#/components/schemas/FinancingTranche' usedAssets: type: array items: $ref: '#/components/schemas/UsedAsset' offerDate: $ref: '#/components/schemas/Date' publicCertDate: $ref: '#/components/schemas/Date' FinancingTranche: description: Tranche of a financing type: object required: - amount - payoutDate - interest - interestRateType properties: productIdRef: type: string format: uuid description: Uuid of the product example: 6e61ff5d-3ffd-4254-a77d-73cc25d35e92 amount: $ref: '#/components/schemas/Amount' payoutDate: $ref: '#/components/schemas/Date' maturityDate: $ref: '#/components/schemas/Date' duration: type: integer minimum: 1 maximum: 20 interest: $ref: '#/components/schemas/Interest' interestRateType: type: string example: libor enum: - variable - libor - saron - fixed saronperiod: type: string description: The saron period. example: 3m enum: - 1m - 3m - 6m - 12m amortizations: $ref: '#/components/schemas/Amortizations' 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' increaseAmount: $ref: '#/components/schemas/Amount' increasePurpose: type: string description: The purpose of the increase. example: renovation of the kitchen 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' requestOfferType: type: string enum: - binding - indicative 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 fiApplicantId: type: string description: ApplicantId of the applicant party defined by the financial institute, only applicable if known at the moment of the application. example: asd23f applicantType: type: string example: individual enum: - individual - legal_entity applicantDetail: type: object properties: name: type: string maxLength: 70 description: Name of the applicant example: Max surName: type: string maxLength: 70 description: Surname of the applicant example: Muster 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 - legally-separated - partnership-dissolved matrimonialPropertyScheme: type: string example: separateEstate enum: - jointEstate - separateEstate - contributionToJointlyAcquiredProperty - none 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 phone: type: string description: Phone number of the applicant example: '+41443343456' solvencyRating: description: Solvency rating of the applicant e.g. CRIF type: object required: - ratingValue - ratingSourceType properties: ratingValue: type: integer description: Solvency rating value example: 420 ratingSourceType: type: string description: Provider of the solvency rating example: crif enum: - crif ratingDate: $ref: '#/components/schemas/Date' description: Date of the solvency rating 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 required: - incomeType - amount properties: incomeType: $ref: '#/components/schemas/IncomeType' amount: $ref: '#/components/schemas/Amount' remark: type: string incomeProvider: description: Income provider for each income or cost position can be transferred. type: string example: Employer AG liabilities: type: array items: type: object required: - liabilityType - amount properties: liabilityType: type: string example: mortgage description: Liability type enum: - leasing - alimony - mortgage - other amount: $ref: '#/components/schemas/Amount' remark: type: string liabilityProvider: description: Name of the liability provider or creditor. type: string example: Leasing Firm AG assets: type: array items: $ref: '#/components/schemas/Asset' residentialSituation: type: string enum: - home_owner - renter example: renter additionalProperties: type: array items: type: object required: - valueAdditionalProperty - propertyTypeAdditionalProperty properties: nameAdditionalProperty: type: string maxLength: 70 description: Name of the additional property example: Orchard Villa, Holderstrasse 10 valueAdditionalProperty: $ref: '#/components/schemas/Amount' description: Value of the additional property propertyTypeAdditionalProperty: type: string enum: - single_family_house - condominium - vacation_house, - vacation_condominium - agricultural_farm - 2or3_family_house - multi_family_house - residential_building_plot - building_plot_other - mixed_property - commercial_condominium - office_building - industrial_building - special_object description: The type of the additional property example: vacation_house # ---- 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 - third_pillar_3a - third_pillar_3b - pension_fund - third_party_loan - third_pillar_fund - third_pillar_fund_3b - third_pillar_fund_3a - fungible_investments - other - vested_benefit - life_insurance_3a - life_insurance_3b - unpledged_building_plot AssetUsageType: description: Common set of asset usage types. type: string example: pledged enum: - pledged - withdraw Asset: description: 'Asset information: Array of all assets the applicant possesses, incl. the assets which will be used for the financial request.' type: object required: - assetType - amount properties: assetType: $ref: '#/components/schemas/AssetType' amount: $ref: '#/components/schemas/Amount' description: The amount of the asset e.g. market value of fungible investment, existing retirement asset in pension fund, surrender value in life insurance insuranceSum: $ref: '#/components/schemas/Amount' description: The amount of the sum insured in life insurance remark: type: string assetProvider: $ref: '#/components/schemas/AssetProvider' UsedAsset: description: 'Asset used by an applicant: Array of all assets which will be used for the financial request. At least, all of these used assets must also be recorded in the array of assets in the financial situation of one applicant.' type: object required: - assetType - amount - applicantId properties: assetType: $ref: '#/components/schemas/AssetType' amount: $ref: '#/components/schemas/Amount' insuranceSum: $ref: '#/components/schemas/Amount' description: The amount of the sum insured in life insurance 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 - leasing_payment - consumer_loan_payment - child_allowance_payment - rental_costs - costs_for_additional_properties 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: 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 remark: type: string example: All documents verified at TPP description: Remark/comment which can be added by TPP 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' Amortizations: description: Information about the amortization on mortgage or on tranche level. type: object properties: amortizationType: type: string enum: - direct - indirect description: The type of amortization example: direct amortizationAmount: $ref: '#/components/schemas/Amount' description: The amount of the periodic amortization example: 27400 amortizationStart: $ref: '#/components/schemas/Date' description: Start date of amortization example: 2018-04-13 amortizationPeriodicity: type: string enum: - yearly - quarterly - monthly description: The periodicity the amortization is paid example: quarterly amortizationAccountNr: type: string description: The account number from which the amortization is paid example: IE12BOFI90000112345678 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: 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: 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 Link: description: Object containing a link to an external resource and its description type: object required: - url properties: url: description: The URL pointing to the resource type: string format: uri minLength: 2 example: http://www.example.com/property.png name: description: The name of the resource type: string example: Property image description: description: A description of the resource type: string example: The image shows the aerial view of the property # ---- Global Common Header Parameters ---- parameters: path_caseId: name: caseId in: path description: Uuid v4 of a specific existing mortgage case required: true schema: type: string format: uuid example: bcb5d762-8d28-43a2-9398-393b2e8d56ba path_mortgageId: name: mortgageId in: path description: Uuid v4 of a specific existing mortgage required: true schema: type: string format: uuid example: bcb5d762-8d28-43a2-9398-393b2e8d56ba path_productId: name: productId in: path description: A product's uuid v4 required: true schema: type: string format: uuid example: a86dd383-055e-471a-a098-682ae5ef8348 path_applicationId: name: applicationId in: path description: Uuid v4 of the application request required: true schema: type: string format: uuid example: 4bf92636-14a0-4511-98e2-acfde576e644 path_documentId: name: documentId in: path description: Unique ID (uuid v4) of the document required: true schema: type: string format: uuid example: 7f648f12-c15f-4930-8380-238da5671c37 path_financingRequestId: name: financingRequestId in: path description: Uuid v4 of the financing request required: true schema: type: string format: uuid example: 1a75e7fc-f3c3-45a9-9268-ec21c405bbc8 path_offerId: name: offerId in: path description: Uuid v4 of the offer required: true schema: type: string format: uuid example: c2fee261-053c-4088-8986-11216f0c9be6 path_orderId: name: orderId in: path description: Uuid v4 of an order required: true schema: type: string format: uuid example: 91d029b3-ee7a-44c3-ac18-cf621cb128a8 clientid_in_header: name: X-CorAPI-Client-ID in: header schema: type: string description: 'ID of the client forwarded to the provider. (SCOPE: FI)' required: true correlation_in_header: name: X-Correlation-ID in: header schema: type: string description: Unique ID (defined by the caller) which will be reflected back in the response. required: true agent_in_header: name: User-Agent in: header 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 duration: name: duration in: query description: The type of duration (for filtering) schema: type: integer minimum: 1 maximum: 20 example: 10 language: name: language in: query description: Language of Document content required: true schema: type: string enum: - de - fr - it - en example: fr # --- Response Headers - used by Standard Responses --- headers: Content-Language: description: Response language - always en schema: type: string Content-Type: description: application/problem+json; charset=utf-8 according to RFC7807 schema: type: string Location: description: Location (submissionId) of the submitted message. Add /status for the status report. schema: type: string X-Correlation-ID: description: Client defined ID from request to correlates HTTP requests between a client and server schema: type: string example: f058ebd6-02f7-4d3f-942e-904344e8cde5 # ---- Responses - Standard---- responses: standard201: description: created content: application/json: schema: $ref: '#/components/schemas/commonResourceCreatedResponse' 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. standard400: headers: Content-Type: $ref: '#/components/headers/Content-Type' Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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: $ref: '#/components/headers/Content-Type' Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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: $ref: '#/components/headers/Content-Type' Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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: $ref: '#/components/headers/Content-Type' Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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: $ref: '#/components/headers/Content-Type' Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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: $ref: '#/components/headers/Content-Type' Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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: $ref: '#/components/headers/Content-Type' Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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: $ref: '#/components/headers/Content-Type' Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' 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