Workflows

This page aims to provide an overview of how to use the ca-mortgage API. It explains Third Party Providers (TPP) the workflow of different use cases the standardized mortgage may support and which endpoints need to be implemented by the TPP to support a specific use case.

Introduction

First, we provide an overview where the ca-mortgage API is used. The API unifies and facilitates the process of making offers and order mortgages. Beside ordering mortgage directly a customer may reach out to a TTP, which negotiates offers (for the customers) with the interface of different FIs.

Possibility 1: The customer reaches out for a FI directly. For every offer the customer provides a new request, which is determined by the requirements of each FI. A lot of customer interaction is required. No TPP is needed. There are two different ways in which the user can interact with the FI: Either the bank provides a Self Service portal, where the user can provide information and request offers. Or the FI implements the front-end for their own customer service representatives trough the common API specification.

Possibility 2: The customer makes a request to the TPP once. The TPP negotiates offers in the background with the FIs without further customer action. This negotiation is done via a common interface that different FIs have implemented. The Common API provides this uniform interface, which enables automation on the part of the TPPs. In the end, the TPP returns to the customer with the negotiated offers. The customer can then also select an offer via the TPP and conclude a binding offer with a FI.

Use Case I: New Mortgage

The first use case describes how customers choose between available mortgages and order a new one. To walk through this process the customer requests a list of available mortgages, provides information about the property and the applicant, requests financing and order, and at the end decides whether and which order the customer would like to fulfill. All these steps are guided by the TPP, which asks the customer to provide the required information and transmit provided data to the mortgage administrator (e.g. bank).

New Mortgage – Overview

The following diagram provides a collection of the steps mentioned above.

New Mortgage – Detailed Description

The next diagram provides a more detailed description of the workflow, including all API endpoints needed to provide the functionality (use case) of applying for a new mortgage. This diagram can be used to determine which endpoints need to be implemented by the TPP to provide this workflow.

New Mortgage – Detailed Description

The next diagram provides a more detailed description of the workflow, including all API endpoints needed to provide the functionality (use case) of applying for a new mortgage. This diagram can be used to determine which endpoints need to be implemented by the TPP to provide this workflow.

A TPP, which wants to provide the functionality of new mortgages, must implement the following endpoint:

• [GET] /mortgages/products
• [GET] /mortgages/products/{productId}/conditions
• [GET] /mortgages/applications/required-information
• [POST] /mortgages/applications
• [PUT] /mortgages/applications/{applicationId}
• [POST] /mortgages/applications/{applicationId}/documents
• [GET] /mortgages/applications/{applicationId}/status
• [POST] /mortgages/applications/{applicationId}/financing-requests
• [GET] /mortgages/applications/{applicationId}/financing-requests/{financingRequestId}
• [GET] /mortgages/applications/{applicationId}/financing-requests/{financingRequestId}/required-information
• [POST] /mortgages/applications/{applicationId}/financing-requests/{financingRequestId}/offers
• [GET] /mortgages/offers/{offerId}/document

Use Case II: Show Mortgage and Extend

The second use case describes how to extend an existing mortgage. In this case, the customer has to select an existing mortgage, update its information, and request a prolonging offer. The TTP coordinates all requests between the customer and the mortgage administrator (e.g. bank) as follows.

Show Mortgage and Extend – Detailed Description

The next diagram provides a more detailed description of the workflow to extend the mortgage. The following diagram can be used to determine which endpoints need to be implemented by the TPP to provide this workflow.

A TPP, which wants to provide the functionality of new mortgages, must implement the following endpoint:

• [GET] /mortgages
• [GET] /mortgages/products
• [GET] /mortgages/products/{productId}/conditions
• [GET] /mortgages/applications/{applicationId}
• [PUT] /mortgages/applications/{applicationId}
• [POST] /mortgages/applications/{applicationId}/documents
• [GET] /mortgages/applications/{applicationId}/status
• [GET] /mortgages/{mortgageId}/offers
• [GET] /mortgages/{mortgageId}/offers/{offerId}
• [POST] /mortgages/orders
• [GET] /mortgages/offers/{offerId}/document