openapi: "3.0.0" info: version: 1.0.0 title: Common Mortgage API (Public) description: This specification defines a common mortgage API for mortgages as used in Switzerland. The API is supposed to be used by requesting parties who want to get, extend, or transfer mortgages from and to financial institutions. This specification uses schema definitions from the Common Data Model v1.2.2. termsOfService: 'Tbd' contact: email: info@common-api.ch license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' servers: - url: mortgage.common-api.ch externalDocs: description: Find out more about SFTI API specifications url: 'https://www.common-api.ch' tags: - name: Existing Mortgages description: Operations related with existing mortgages - name: Mortgage Products and Conditions description: Operations for synchronizing general mortgage product information from an FI - name: Mortgage Application description: Operations needed to place an application (dossier) for a new mortgage - name: Mortgage Financing Request description: Operations for handling financing requests for a specific accepted application (dossier) - name: Mortgage Offers description: Operations for handling the binding offers an FI provides - name: Mortgage Order description: Operations for placing a binding order for a chosen offer - name: Mortgage Prolongation description: Operations for handling the common special case of prolonging an existing mortgage security: - ApiKeyAuth: [] - OAuth2: - read - write paths: /mortgages: get: tags: - Existing Mortgages description: List of mortgages for the authenticated context including the corresponding properties and related mortgages, sorted by mortgageId. summary: Return the list of all mortgages for the authenticated context parameters: - in: query name: expiring schema: type: boolean example: true description: Whether or not the mortgage is qualified for being prolonged, i.e., expiring soon or already expired (for filtering) - in: query name: limit schema: type: integer example: 25 description: Optional parameter for pagination. Maximum number of entries to be returned. - in: query name: offset schema: type: integer example: 26 description: Optional parameter for pagination. Start entry to be returned. responses: '200': description: Paginated list of all mortgages with all related information sorted by mortgageId content: application/json: schema: type: object properties: MortgageList: type: array items: $ref: '#/components/schemas/Mortgage' _links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/{mortgageId}: get: tags: - Existing Mortgages description: A specific existing mortgage including the corresponding properties and related mortgages. summary: Return a specific existing mortgage parameters: - name: mortgageId in: path description: ID of a specific existing mortgage required: true example: bankx-mortgage-234434 schema: type: string responses: '200': description: Mortgage details with the corresponding properties and related mortgages. content: application/json: schema: type: object properties: Mortgage: $ref: '#/components/schemas/Mortgage' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/products: get: summary: Get a list of all mortgage products description: Get a complete overview of all available mortgage products sorted by productId tags: - Mortgage Products and Conditions parameters: - in: query name: interestRateType schema: type: string example: saron enum: - variable - libor - saron - fixed description: The type of the interest rates (for filtering) - in: query name: interestBasis schema: type: string description: The basis of the interest (for filtering) - in: query name: durationType schema: type: integer minimum: 1 maximum: 20 example: 10 description: The type of duration (for filtering) - in: query name: limit schema: type: integer example: 25 description: Optional parameter for pagination. Maximum number of entries to be returned. - in: query name: offset schema: type: integer example: 26 description: Optional parameter for pagination. Start entry to be returned. responses: '200': description: Paginated list of all mortgage products with all related information sorted by productId content: application/json: schema: type: object properties: productList: type: array items: $ref: '#/components/schemas/Product' _links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/products/{productId}/conditions: get: summary: Get the general conditions for the specified mortgage product description: The standard financial conditions for the product tags: - Mortgage Products and Conditions parameters: - in: path name: productId schema: type: string required: true example: bankx-product-234 description: A product's unique ID - in: query name: duration schema: type: string description: The duration (for filtering) - in: query name: interest schema: type: string description: The interest (for filtering) responses: '200': description: List of conditions related to a specific mortgage product. content: application/json: schema: type: object properties: conditionList: type: array items: $ref: '#/components/schemas/Condition' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications: post: summary: Place a new mortgage application (serves as dossier) description: Place a new application including all necessary information about the property and applicant’s financial situation. **Note that in the case where the FI needs additional information on the property, the error response 400 must contain the minimum required JSON object (PropertyObject) as detail**. tags: - Mortgage Application requestBody: description: Static details (requesting party, property object) of the application to be added as a dossier required: true content: application/json: schema: $ref: '#/components/schemas/Application' responses: '201': description: created headers: location: schema: type: string format: uri description: link to the created resource '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/required-information: get: summary: Get the required property information for the specific FI needed for valuation description: Show the subset of property details required by the FI for valuation tags: - Mortgage Application responses: '200': description: OK content: application/json: schema: type: object $ref: '#/components/schemas/PropertyObject' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}: get: summary: Get the details of a specific placed application description: Get the details of a specific placed application tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string required: true example: bankx-applicationreq-465234 description: Unique ID of the application request responses: '200': description: OK content: application/json: schema: type: object properties: application: $ref: '#/components/schemas/Application' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' put: summary: Update the application’s details description: Update the application’s details. Note that changing the application's details should not be possible after the application has been accepted by the FI. tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string required: true example: bankx-applicationreq-465234 description: Unique ID of the application request requestBody: description: Details of the order to be added required: true content: application/json: schema: $ref: '#/components/schemas/Application' responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' delete: summary: Cancel the application and removing it description: Cancel the application and removing it tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string required: true example: bankx-applicationreq-465234 description: Unique ID of the application request responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/swissrets: post: summary: Add property details in the SwissRETS standard description: This endpoint allows to upload the real estate property's details as an XML file in the SwissRETS format according to https://swissrets.ch/ tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string required: true example: bankx-applicationreq-465234 description: Unique ID of the application request requestBody: description: Details of the real estate property to be added required: true content: application/xml: schema: type: string responses: '201': description: created headers: location: schema: type: string format: uri description: link to the created resource '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' get: summary: Get property details in SwissRETS format description: Get the real estate property's details in SwissRETS format XML according to https://swissrets.ch/ tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string example: bankx-applicationreq-465234 required: true description: Unique ID of the application request responses: '200': description: OK content: application/xml: schema: type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' put: summary: Update the real estate property's details description: This endpoint allows to upload a modified XML file in the SwissRETS format changing the already existing information tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string required: true example: bankx-applicationreq-465234 description: Unique ID of the application request requestBody: description: Details of the real estate property to be added required: true content: application/xml: schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/documents: post: summary: Add documents for the specific application description: Add to a specific application’s documents tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string required: true example: bankx-applicationreq-465234 description: Unique ID of the application request requestBody: description: Details of the document to be added required: true content: multipart/form-data: schema: type: object properties: filename: type: string format: binary responses: '201': description: created headers: location: schema: type: string format: uri description: link to the created resource '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' get: summary: Get a list of submitted documents for a specifically placed application description: Get a list of documents submitted for a specifically placed application tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string example: bankx-applicationreq-465234 required: true description: Unique ID of the application request responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: filename: type: string filetype: type: string filesize: type: integer uploaddate: $ref: '#/components/schemas/Date' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/documents/{documentId}: delete: summary: Delete a formerly uploaded document description: Deletes a specific document attached to a specific application. Note that deleting documents should not be possible after the application has been accepted by the FI. tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string example: bankx-applicationreq-465234 required: true description: Unique ID of the application (dossier) - in: path name: documentId schema: type: string example: bankx-application-document-3445 required: true description: Unique ID of the document responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/status: get: summary: Get the current status of the application description: Get the current status of the application (rejected with reason, accepted, pending with reason) tags: - Mortgage Application parameters: - in: path name: applicationId schema: type: string example: bankx-applicationreq-465234 required: true description: Unique ID of the application request responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string enum: - accepted - rejected - pending example: pending detail: type: string example: Waiting for details '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/financing-requests: post: summary: Place a new financing-request for a specific accepted application (dossier) description: Place a new financing request including all necessary information tags: - Mortgage Financing Request parameters: - in: path name: applicationId schema: type: string example: bankx-applicationreq-465234 required: true description: Unique ID of the application request requestBody: description: Specific financing request fo the given application (dossier) required: true content: application/json: schema: $ref: '#/components/schemas/FinancingRequest' responses: '201': description: created headers: location: schema: type: string format: uri description: link to the created resource '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/financing-requests/{financingRequestId}/offers: get: summary: List all binding offers for a given financing request description: List all binding offers for a given application tags: - Mortgage Offers parameters: - in: path name: applicationId schema: type: string example: bankx-applicationreq-465234 required: true description: Unique ID of the application request - in: path name: financingRequestId schema: type: string example: bankx-financingreq-35623 required: true description: Unique ID of the financing request responses: '200': description: OK content: application/json: schema: type: object properties: offerList: type: array items: $ref: '#/components/schemas/Offer' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/applications/{applicationId}/financing-requests/{financingRequestId}/offers/{offerId}: get: summary: Get the details of a specific offer description: Get the details of a specific offer for a specific placed application tags: - Mortgage Offers parameters: - in: path name: applicationId schema: type: string example: bankx-applicationreq-465234 required: true description: Unique ID of the application request - in: path name: financingRequestId schema: type: string example: bankx-financingreq-35623 required: true description: Unique ID of the financing request - in: path name: offerId schema: type: string example: bankx-offer-35465 required: true description: Unique ID of the offer responses: '200': description: OK content: application/json: schema: type: object properties: offer: $ref: '#/components/schemas/Offer' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/orders: post: summary: Place a new order description: Place a new order referencing a specific offerId and either an existing mortgage id (prolongation) or an application id (new mortgage) including all relevant information tags: - Mortgage Order requestBody: description: Details of the order to be added required: true content: application/json: schema: $ref: '#/components/schemas/Order' responses: '201': description: created headers: location: schema: type: string format: uri description: link to the created resource '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/orders/{orderId}: get: summary: Get the details of a specific placed order description: Get the details of a specific placed order tags: - Mortgage Order parameters: - in: path name: orderId schema: type: string example: bankx-order-6464 required: true description: Unique ID of an order responses: '200': description: OK content: application/json: schema: type: object properties: offer: $ref: '#/components/schemas/Order' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/orders/{orderId}/status: get: summary: Get the current status of the order description: Get the current status of the order (rejected with reason, accepted, pending with reason) tags: - Mortgage Order parameters: - in: path name: orderId schema: type: string example: bankx-order-6464 required: true description: Unique ID of an order responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string enum: - accepted - rejected - pending example: pending detail: type: string example: Waiting for details '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/{mortgageId}/offers: get: tags: - Mortgage Prolongation description: Get offer framework for the to be extended mortgage. summary: Get all active offers for a specific tranche parameters: - name: mortgageId in: path description: ID of a specific expiring mortgage required: true example: bankx-mortgage-354663 schema: type: string responses: '200': description: Paginated list of all offers for a specific expiring mortgage content: application/json: schema: type: object properties: offerList: type: array items: $ref: '#/components/schemas/Offer' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /mortgages/{mortgageId}/offers/{offerId}: get: tags: - Mortgage Prolongation description: Get a specific offer for the to be extended mortgage. summary: Get a specific offer for a specific tranche parameters: - name: mortgageId in: path description: ID of a specific expiring mortgage example: bankx-mortgage-354663 required: true schema: type: string - name: offerId in: path description: ID of a specific mortgage prolongation offer example: bankx-offer-35465 required: true schema: type: string responses: '200': description: Specific offer for a specific expiring mortgage content: application/json: schema: type: object properties: offer: $ref: '#/components/schemas/Offer' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' # ------------------------- # -------- Models --------- # ------------------------- components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://example.com/oauth/token scopes: read: Grants read access write: Grants write access schemas: # ---- Common Data Model v1.2.0 # ---- Date Formats Date: type: string format: date example: 2018-04-13 DateTime: type: string format: date-time example: 2018-04-13T11:11:11Z # -------- # ---- Links ---- Links: description: links returned in the answer of an API call type: object properties: self: type: string first: type: string previous: type: string next: type: string last: type: string # --------- # ---- Currency ---- Currency: description: ISO 4217 code type: string pattern: '[A-Z]{3}' example: CHF # --------- # ---- Amount ---- Amount: description: amount with currency type: object required: - currency - content properties: currency: $ref: '#/components/schemas/Currency' content: description: amount given with fractional digits, the separator is a dot type: string pattern: '-?\d{1,14}(?:\.\d{1,3})?' example: 235.45 # -------- # ---- Address compliant to payment address (b.Link & ISO20022)---- structuredAddress: title: Structured Address type: object required: - streetName - postCode - townName - country properties: streetName: type: string maxLength: 70 example: "Rue de la gare" buildingNumber: type: string maxLength: 16 example: "24" postCode: type: string maxLength: 16 example: "2501" townName: type: string maxLength: 35 example: "Biel" country: type: string maxLength: 2 example: "CH" unstructuredAddress: title: Unstructured Address type: object required: - addressLines - country properties: addressLines: type: array description: max 2 lines of 70 characters maxLength: 2 example: ["Robert Schneider SA", "Rue de la gare 24"] items: type: string maxLength: 70 country: type: string maxLength: 2 example: "CH" structuredOrUnstructuredAddress: title: Structured or Unstructured Address description: Either structured or unstructered must be set type: object properties: structured: $ref: '#/components/schemas/structuredAddress' unstructured: $ref: '#/components/schemas/unstructuredAddress' # ----------- # ---- Country Code ---- Country: type: string pattern: '[A-Z]{2}' example: CH description: 2-Letter ISO 3166-2 Country Code # ------------ # ---- Error Response (compliant to SIX b.Link) commonErrorResponse: title: Common Error Response type: object properties: type: $ref: '#/components/schemas/commonErrorType' title: type: string example: This is the general problem description detail: type: string example: Detailed problem description with respect to the current request instance: type: string example: path/to/corresponding/resource commonErrorType: title: Common Error Type description: Error Types for commonErrorResponse. type: string enum: - /problems/INVALID_PAYLOAD - /problems/MALFORMED_PAYLOAD - /problems/INVALID_TOKEN - /problems/EXPIRED_TOKEN - /problems/INSUFFICIENT_PRIVILEGES - /problems/NO_ACCESS_TO_RESOURCE - /problems/RESOURCE_DOES_NOT_EXIST - /problems/RESOURCE_NOT_READY - /problems/RESOURCE_TOO_LARGE - /problems/WRONG_METHOD - /problems/OPERATION_NOT_ALLOWED - /problems/TECHNICAL_ERROR - /problems/NOT_IMPLEMENTED - /problems/SERVICE_UNAVAILABLE example: '/problems/TECHNICAL_ERROR' # ---- End Error Response # ---- End Common Data Model # ---- Property Object ---- PropertyObject: description: The representation of a real estate object, real estate register id (propertyIdentifier) is optional until otherwise required by law type: object required: - propertyObjectId - name - address properties: propertyObjectId: type: string example: propertyID-436563 name: type: string example: My Nice Property objectType: type: string example: house enum: - apartment - house - garage - other #### At the moment we consider only mortgages for self-occupied real estate #usageType: # type: string address: $ref: '#/components/schemas/structuredAddress' propertyIdentifier: $ref: '#/components/schemas/PropertyIdentifier' luxuryLevel: type: string example: yes enum: - 'yes' - 'no' landArea: type: integer netDwellingArea: type: integer volume: type: object properties: amount: type: integer standard: type: string #enum: # what standards are considered? buildYear: type: integer example: 1929 lastRenovationYear: type: integer example: 1980 buildingCondition: # Range? type: integer buildingQuality: # Range? type: integer rooms: type: number example: 4 roomCountingStrategy: type: string bathRooms: type: integer example: 2 closets: type: integer example: 1 parkingLots: type: integer example: 4 undergroundParkingLots: type: integer example: 0 dedicatedGarages: type: integer example: 1 minergieStandard: type: string #enum: # values? valueRelevantServitudes: type: string objectPrice: type: integer example: 3544344 purchaseDate: $ref: '#/components/schemas/Date' remarks: type: string # --------- # ---- Property Identifier ---- PropertyIdentifier: description: Property identification (register of real estate) type: object properties: EGRID: type: string EGID: type: string # --------- # ---- Mortgage ---- Mortgage: description: All relevant information regarding a specific mortgage type: object required: - mortgageId - product - amountAtExpiry - validFrom - validTo - interestRate - interestRateType - interestBasis - durationType - prolongable - propertyObjects - linkRef properties: mortgageId: type: string example: bankx-mortgage-354663 product: $ref: '#/components/schemas/Product' amountAtExpiry: $ref: '#/components/schemas/Amount' amountToday: $ref: '#/components/schemas/Amount' validFrom: $ref: '#/components/schemas/Date' validTo: $ref: '#/components/schemas/Date' interestRate: type: string interestRateType: type: string example: libor enum: - variable - libor - saron - fixed interestBasis: type: string durationType: type: integer example: 10 minimum: 1 maximum: 20 prolongable: type: boolean propertyObjects: type: array items: $ref: '#/components/schemas/PropertyObject' relatedMortgages: type: array items: $ref: '#/components/schemas/Mortgage' linkRef: type: string # --------- # ---- Mortgage Offer ---- Offer: description: All relevant details describing the FI's offer for a mortgage product type: object required: - offerId - financingRequestIdRef - totalAmount - validTo - offerItems - linkRef properties: offerId: type: string example: bankx-offer-35465 financingRequestIdRef: type: string example: bankx-applicationreq-465234 totalAmount: $ref: '#/components/schemas/Amount' validTo: $ref: '#/components/schemas/Date' offerItems: type: array items: $ref: '#/components/schemas/OfferItem' linkRef: type: string # --------- # ---- Mortgage Offer Item ---- OfferItem: description: All relevant details of a specific item being part of an FI's offer for a mortgage product type: object required: - offerItemId - product - conditions properties: offerItemId: type: string example: bankx-offer-35465 product: $ref: '#/components/schemas/Product' conditions: type: array items: $ref: '#/components/schemas/Condition' # --------- # ---- Mortgage Product ---- Product: description: All details regarding an FI's mortgage product type: object required: - productId - name - interestRateType - interestBasis - durationType properties: productId: type: string example: bankx-product-234 name: type: string example: Nice Mortgage Product Large interestRateType: type: string example: libor enum: - variable - libor - saron - fixed interestBasis: type: string durationType: type: integer example: 10 minimum: 1 maximum: 20 # --------- # ---- Mortgage Product Condition ---- Condition: description: All details regarding the conditions for a specific mortgage product the FI offers type: object required: - conditionId - productIdRef - duration - maturityDate - interest - amountRange - increment properties: conditionId: type: string example: bankx-condition-45434 productIdRef: type: string example: bankx-product-234 duration: type: string maturityDate: $ref: '#/components/schemas/Date' interest: $ref: '#/components/schemas/Interest' amountRange: $ref: '#/components/schemas/AmountRange' increment: type: integer # --------- # ---- Party ---- Party: description: Links together the persons building the applicant party type: object required: - personList properties: personList: type: array items: type: object $ref: '#/components/schemas/Applicant' # --------- # ---- Application ---- Application: description: All static application information needed by the FI to create binding offers type: object required: - applicationId - requestingParty - propertyInformation properties: applicationId: type: string example: bankx-application-46543 requestingParty: $ref: '#/components/schemas/Party' propertyInformation: $ref: '#/components/schemas/PropertyObject' # --------- # ---- Financing Request ---- FinancingRequest: description: Based on the application, several financing requests can be sent to the FI type: object required: - financingRequestId - applicationIdRef - amount properties: financingRequestId: type: string example: bankx-applicationreq-465234 applicationIdRef: type: string example: bankx-application-46543 amount: $ref: '#/components/schemas/Amount' tranches: type: array items: type: object properties: productId: type: integer amount: $ref: '#/components/schemas/Amount' usedAssets: type: object properties: amountTotal: type: integer amountPledged: type: integer payOutDate: $ref: '#/components/schemas/Date' publicCertDate: $ref: '#/components/schemas/Date' # --------- # ---- Applicant ---- Applicant: description: Applicant information needed by the FI for creating a binding offer type: object required: - applicantType - applicantDetail properties: applicantType: type: string enum: - individual - legal entity applicantDetail: type: object properties: name: type: string maxLength: 70 example: Muster surName: type: string maxLength: 70 example: Max address: $ref: '#/components/schemas/structuredAddress' birthDate: $ref: '#/components/schemas/Date' maritalStatus: type: string example: married enum: - unmarried - married - divorced - widowed matrimonialPropertyScheme: type: string example: separateEstate enum: - jointEstate - separateEstate - contributionToJointlyAcquiredProperty jobSituation: type: string example: employed enum: - employed - selfEmployed - unemployed - retired nationality: $ref: '#/components/schemas/Country' USPerson: type: boolean example: false email: type: string example: max.muster@domain.ch applicantLanguage: type: string example: fr enum: - de - fr - it - en financialSituation: type: object properties: income: type: array items: type: object properties: incomeType: type: string example: salary enum: - salary - pension - alimony - rent - other amount: $ref: '#/components/schemas/Amount' remark: type: string ######## Special case for applicants running into retirement age: Postponed for the moment #estimatedRetirementIncome: # $ref: '#/components/schemas/Amount' liabilities: type: array items: type: object properties: liabilityType: type: string example: mortgage enum: - leasing - alimony - mortgage - other amount: $ref: '#/components/schemas/Amount' remark: type: string assets: type: array items: type: object properties: assetCategory: type: string example: cash enum: - cash - thirdPillar - pensionFund - fungibleInvestments - other valuation: $ref: '#/components/schemas/Amount' # --------- # ---- Order ---- Order: description: All information needed to choose a specific offer and place a binding order. If it is a prolongation, then the mortgageId of the expiring mortgage must be referenced. Otherwise the applicationId of the application for a new mortgage. Note that the prolongation use case can also be handled by the new mortgage use case (special case). type: object required: - offerId - amount - offeredInterest properties: offerId: type: string example: bankx-offer-35465 mortgageId: type: string example: bankx-mortgage-234434 applicationId: type: string example: bankx-application-46543 amount: $ref: '#/components/schemas/Amount' offeredInterest: $ref: '#/components/schemas/Interest' validateOnly: type: boolean example: true status: type: string # --------- # ---- AmountRange ---- AmountRange: description: Min and max amount with currency type: object required: - currency - minContent - maxContent properties: currency: $ref: '#/components/schemas/Currency' minContent: description: min amount given with fractional digits, the separator is a dot type: string pattern: '-?\d{1,14}(?:\.\d{1,3})?' example: 1000000 maxContent: description: max amount given with fractional digits, the separator is a dot type: string pattern: '-?\d{1,14}(?:\.\d{1,3})?' example: 5000000 # --------- # ---- Interest ---- Interest: description: The current rate and optionally the referred base type: object required: - currentRate properties: currentRate: type: string pattern: '-?\d{1,3}(?:\.\d{1,3})?' base: type: string pattern: '-?\d{1,3}(?:\.\d{1,3})?' # --------- # ---- Responses - Standard Errors Common Data Model v1.2.2---- responses: standard400: headers: Content-Type: schema: type: string description: 'application/problem+json; charset=utf-8 according to RFC7807' example: application/problem+json Content-Language: schema: type: string description: 'Response language - always en' example: en X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. example: f058ebd6-02f7-4d3f-942e-904344e8cde5 description: Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error as malformed request syntax. content: application/problem+json: schema: $ref: '#/components/schemas/commonErrorResponse' standard401: headers: Content-Type: schema: type: string description: 'application/problem+json; charset=utf-8 according to RFC7807' example: application/problem+json Content-Language: schema: type: string description: 'Response language - always en' example: en X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. example: f058ebd6-02f7-4d3f-942e-904344e8cde5 description: Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource. content: application/problem+json: schema: $ref: '#/components/schemas/commonErrorResponse' standard403: headers: Content-Type: schema: type: string description: 'application/problem+json; charset=utf-8 according to RFC7807' example: application/problem+json Content-Language: schema: type: string description: 'Response language - always en' example: en X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. example: f058ebd6-02f7-4d3f-942e-904344e8cde5 description: Forbidden - The server understood the request but refuses to authorize it. content: application/problem+json: schema: $ref: '#/components/schemas/commonErrorResponse' standard404: headers: Content-Type: schema: type: string description: 'application/problem+json; charset=utf-8 according to RFC7807' example: application/problem+json Content-Language: schema: type: string description: 'Response language - always en' example: en X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. example: f058ebd6-02f7-4d3f-942e-904344e8cde5 description: Not Found - The origin server did not find a current representation for the target resource or is not willing to disclose that one exists. content: application/problem+json: schema: $ref: '#/components/schemas/commonErrorResponse' standard405: headers: Content-Type: schema: type: string description: 'application/problem+json; charset=utf-8 according to RFC7807' example: application/problem+json Content-Language: schema: type: string description: 'Response language - always en' example: en X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. example: f058ebd6-02f7-4d3f-942e-904344e8cde5 description: Method Not Allowed - The method received in the request-line is known by the origin server but not supported by the target resource. content: application/problem+json: schema: $ref: '#/components/schemas/commonErrorResponse' standard500: headers: Content-Type: schema: type: string description: 'application/problem+json; charset=utf-8 according to RFC7807' example: application/problem+json Content-Language: schema: type: string description: 'Response language - always en' example: en X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. example: f058ebd6-02f7-4d3f-942e-904344e8cde5 description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request. content: application/problem+json: schema: $ref: '#/components/schemas/commonErrorResponse' standard501: headers: Content-Type: schema: type: string description: 'application/problem+json; charset=utf-8 according to RFC7807' example: application/problem+json Content-Language: schema: type: string description: 'Response language - always en' example: en X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. example: f058ebd6-02f7-4d3f-942e-904344e8cde5 description: Not Implemented - The server does not support the functionality required to fulfill the request. content: application/problem+json: schema: $ref: '#/components/schemas/commonErrorResponse' standard503: headers: Content-Type: schema: type: string description: 'application/problem+json; charset=utf-8 according to RFC7807' example: application/problem+json Content-Language: schema: type: string description: 'Response language - always en' example: en X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. example: f058ebd6-02f7-4d3f-942e-904344e8cde5 description: Service Unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance. content: application/problem+json: schema: $ref: '#/components/schemas/commonErrorResponse' # ---- End Responses - Standard Errors