As a bank I’d like my customers to see the difference between a repayment mortgage and an interest-only mortgage so they can choose what’s right for them

The Problem

People get confused and unable to select the type of a mortgage that suits them because they don't understand the impact of each type on their financial status.

The Solution

Create a user friendly application which captures all the necessary details about the clients' household, their future goals and calculate the impact their mortgage will have long term.

For this scenario we will be focusing on a millennial couple with no kids, trying to buy a house.

The Flow

The following steps can be taken to get to the result.

1. Create a Household
2. Add all the persons in the household complete with their health status which can have an impact on their longevity
3. Add the incomes the household generates
4. Add the expenses the household incurs
5. Add all the assets the household possesses (the house they live in with a repayment loan)
6. Setting up a retirement goal for the persons in the household
7. Run a simulation of the household to get a forecast of the future
8. Read the results of the simulation
9. Modify the type of house mortgage to interest-only
10. Re-run the simulation on the updated household with the pension contribution
11. Examine and compare the results post retirement.

Flow Breakdown

Setup and Authentication

These are necessary steps to authenticate with the API. For the users a Guest account will be used.

export CLIENT_ID=YOUR_CLIENT_ID
export CLIENT_SECRET=YOUR_CLIENT_SECRET
  
export AUTHORIZATION=`echo -n $CLIENT_ID:$CLIENT_SECRET | base64`
curl -X POST 'https://api.envizage.me/uaa/oauth/token' \
    -H "Accept: application/json" \
    -H "Authorization: Basic $AUTHORIZATION" \
    -d "grant_type=client_credentials"

The response will be a json object containing the access token for the service account. Grab the access_token from the response and create a guest user.

curl 'https://api.envizage.me/uaa/guest/login' -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}<access_token>"

The response will contain the access token for the newly created guest user.

{
    "token": {
        "accessToken":"<GUEST_ACCESS_TOKEN>",
        "tokenType":"bearer",
        "refreshToken":"<GUEST_REFRESH_TOKEN>",
        "expiresIn":899
    }
}

Save the accessToken and use it in all subsequent requests.

With the Setup done, follow the business flow.

1. Create a Household

A household is a family, a person or a group of persons sharing an account which consolidates multiple financial items.

We will create a household named "My Household":

curl -X POST \
  https://api.envizage.me/households \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My household"
    }'

Save the 'id' from the response as you will need it in subsequent requests.

2. Add the persons to the household

2.1 Set up a primary person for the household

When a household is created, a primary person is also created. To set the correct values for the person, it has to be updated with the correct values.

The presence of the primary person is mandatory. She/he is the person who the agent will talk to and whose life will assess.

In order to set the primary up, first we obtain the primary person, get the id.

curl -X GET \
  https://api.envizage.me/households/<household_id>/persons/primary \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

Next update the primary person with the desired values.

curl -X POST \
  https://api.envizage.me/households/<household_id>/persons/partner \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "name" : "Me",
        "yearOfBirth" : 1980,
        "primary" : true,
        "gender" : "MALE",
        "maritalStatus" : "MARRIED",
        "healthStatus" : "EXCELLENT",
        "jobType" : "ACTIVE",
        "expectedRetirementAge" : 67
      }'

2.2 Add a partner to the primary person

We will simulate a 2 persons household and will

Envizage currently supports single person and two person households with or without children.

To add a partner to the primary person, execute the following command:

curl -X POST \
  https://api.envizage.me/households/<household_id>/persons/partner \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "name" : "Anne",
        "lastName" : "Smith",
        "yearOfBirth" : 1980,
        "primary" : false,
        "gender" : "FEMALE",
        "maritalStatus" : "MARRIED",
        "healthStatus" : "EXCELLENT",
        "jobType" : "ACTIVE",
        "expectedRetirementAge" : 67
    }'

3. Add the income the household generates

In this scenario both persons are employed full time and have an annual income. The following two calls, will set up an annual income (salary) for each person.

The primary person's income:

curl -X POST \
  https://api.envizage.me/households/<household_id>/incomes/earned \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name" : "My earned income",
  "frequency" : "ANNUALLY",
  "amount" : 40000.0,
  "currency" : "GBP",
  "startDate" : "2019-01-01T00:00:00Z",
  "startsOn" : "USER_DEFINED",
  "endDate" : "2040-01-01T00:00:00Z",
  "endsOn" : "ON_RETIREMENT",
  "growthRate" : "CALCULATED"
}'

Partner's income:

curl -X POST \
  https://api.envizage.me/households/<household_id>/persons/<partner_id>/incomes/earned \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name" : "My partner'\''s earned income",
  "frequency" : "ANNUALLY",
  "amount" : 20000.0,
  "currency" : "GBP",
  "startDate" : "2019-01-01T00:00:00Z",
  "startsOn" : "USER_DEFINED",
  "endDate" : "2040-01-01T00:00:00Z",
  "endsOn" : "ON_RETIREMENT",
  "growthRate" : "CALCULATED"
}'

4. Add the expenses the household incur

Every household has expenses. Although Envizage allows all types of granularity, from our experience we found that people know their estimated monthly expenses best. The following call sets up a monthly living expense entry which covers everything from rent to restaurants. This is roughly how much the couple spends roughly in a month.

curl -X POST \
  https://api.envizage.me/households/<household_id>/expenses/living \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name" : "My living expense",
  "frequency" : "MONTHLY",
  "amount" : 2900,
  "currency" : "GBP",
  "startDate" : "2019-01-01T00:00:00Z",
  "startsOn" : "USER_DEFINED",
  "endDate" : "2019-01-01T00:00:00Z",
  "endsOn" : "ON_DEATH",
  "growthRate" : "CALCULATED",
  "nonDiscretionaryPercentage" : 0.75,
  "survivorAdjustmentPercentage" : 0.75
}'

5. Add the residential property and mortgage

The partners are new homeowners and live in their property. The property also has a mortgage attached to it.

5.1 Add the primary residential property

Primary means, that the couple lives in it.

curl -X POST \
  https://api.envizage.me/households/{householdId}/cbf165f7bb6ac0013a5a537/assets/properties/residential/ \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'content-type: application/json;charset=UTF-8' \
  -d '{
    "source": "manual entry",
    "value": 500000,
    "primary": true,
    "currency": "GBP",
    "country": "UK",
    "valuationDate": "2019-04-17T15:59:43.278Z",
    "name": "House"
}'

Save the returned ID of the newly created property, because we need to use it when attaching a mortgage to it.

5.2 Add the mortgage to the property

curl -X POST \
  https://api.envizage.me/households/{householdId}/cbf165f7bb6ac0013a5a537/liabilities/mortgages/ \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'content-type: application/json;charset=UTF-8' \
  -d '{
    "amount": 350000,
    "balanceAmount": 0,
    "currency": "GBP",
    "startDate": "2019-04-17T16:05:30.729Z",
    "endDate": "2045-04-17T16:05:30.729Z",
    "balanceDate": "2019-04-17T16:05:30.730Z",
    "fixedRateValue": 0.03,
    "fixedRate": true,
    "interestOnly": false,
    "variableRateSpread": 0,
    "variableRateIndex": 0,
    "propertyAssetId": "<PROPERTY_ID>",
    "name": "Mortgage"
}'

6. Setting up goals

Goals are the key milestones in a household’s future plans. They represent the major aspirations of the household, and may vary over time.

6.1 Create Retirement goals

For the simulation to be effective, retirement needs to be taken into consideration. We will create the retirement goal for the primary person.

To set the correct year for retirement, we will simply add the desired retirement age to the year of birth.

For the primary this will be 1980 + 67 = 2047.

curl -X POST \
  https://api.envizage.me/households/{householdId}/cb4acbefca5820013e16f5d/goals/typed \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Retirement",
  "type": "RETIREMENT",
  "minimumAmount": 0,
  "desiredAmount": 0,
  "currency": "USD",
  "startDate": "2048-01-01T00:00:00Z",
  "endDate": "2048-01-01T00:00:00Z",
  "frequency": "ONE_OFF",
  "priority": 5,
  "properties": {
    "percentageOfPreRetirementSpendAfterFirst10Years": 1,
    "percentageOfPreRetirementSpendFirst10Years": 1,
    "percentageOfSurvivorExpenditureSpend": 1,
    "tradeDownDate": "2047-01-01T00:00:00Z",
    "tradeDownHouse": false,
    "tradeDownNewHousePercentage": 1
  }
}'

There are several types of goal which all have a financial impact on the household, but we will omit those for brevity.

7. Run the simulation and check the outcome

We are ready to see what the future looks like for this household. To do this, a simulation will be run for this household. This is called a scenario.

Whenever a household is created, a scenario is also created and this household is made part of it. To run the simulation, we need to know which scenario we are running.

7.1 Obtain the scenario id

Let's obtain the scenario id with the following call:

curl -X GET \
  https://api.envizage.me/households/<household_id>/scenario \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

The payload will contain the whole configuration of the scenario. We are interested only in the ID.

7.2 Execute the scenario

The following call will execute the scenario

curl -X GET \
  https://api.envizage.me/households/<household_id>/scenario/execute/<scenario_id> \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'resultMode: REAL'

The response will be 200 OK which means that the execution was dispatched successfully.

8. Reading the results of the simulation

8.1 Query the simulation result

curl -X GET \
  https://api.envizage.me/results/<scenario_id>/achievability/goal \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

The result will contain all the goals (2 in our case) set up for this household and some data to work out the achievability score for each.

The following example shows the result for the goal with the id 5cb5bec7799f0100148e0105.

{
    "id": "5cb5bed5a1e2640011ddbced",
    "name": null,
    "description": null,
    "totalLives": 500,
    "totalAlive": 490,
    "totalAchieved": 248,
    "totalNotAchieved": 242,
    "goalId": "5cb5bec7799f0100148e0105"
}

Field	Description
totalLives	The number of simulations for this household.
totalAlive	How many times the primary person was alive when reaching the goal.
totalAchieved	How many times the goal was afforded.
totalNotAchieved	How many times the household could not afford the goal.

Based on this summary of data we can draw the following conclusions:

• There is a 5% chance that the primary person will die before the year the goal is wished for
• There is slightly over 50% chance to afford the goal

There are a few factors that can influence a goal achievability in a two person household.

But let's check the timeline of the household.

8.2 Get the scenario result

The scenario result is a time series of yearly data points carrying the most common values from a yearly balance sheet.

To get the scenario result execute the following API call:

curl -X GET \
  https://api.envizage.me/results/<scenario_id>/data \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

The result contains both median (most probable) and grouped data.

Following is an example single data point:

{
    "TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": 3418.249245934494,
    "TOTAL_ASSETS_TAX_ADVANTAGED": 0,
    "TOTAL_ASSETS_PENSION": 0,
    "TOTAL_ASSETS_PHYSICAL_ASSETS": 0,
    "TOTAL_ASSETS_PROPERTY": 204062.83694673632,
    "LIABILITY_MORTGAGE_ON_RESIDENTIAL_PROPERTY_TOTAL": 0,
    "LIABILITY_MORTGAGE_ON_OTHER_PROPERTY_TOTAL": 0,
    "LIABILITY_OTHER_LOAN_TOTAL": 0,
    "LIABILITY_STUDENT_LOAN_TOTAL": 0,
    "AVAILABLE_NET_WORTH_TOTAL": 3418.2492459344794,
    "NET_WORTH_TOTAL": 207481.0861926708,
    "WILL_I_HAVE_MONEY": 0.988,
    "TOTAL_LIVES": 500,
    "TOTAL_ALIVE": 500
}

And following is the grouped data points:

The grouping in the example is as follows:

• 0%-30% - this band contains the worst performing 30% of the total lives which are alive in this time step
• 30%-50% - this band contains the 20% of the total lives which are alive in this time step and performed better than the previous group
• 50%-70% - this band contains the 20% of the total lives which are alive in this time step and performed better than the previous (*50%-70%) group
• 70%-100% - this band contains the 30% of the total lives which are alive in this time step and performed best

{
    "0": {
        "TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": -546949.8543955603,
        "TOTAL_ASSETS_TAX_ADVANTAGED": 0,
        "TOTAL_ASSETS_PENSION": 0,
        "TOTAL_ASSETS_PHYSICAL_ASSETS": 0,
        "TOTAL_ASSETS_PROPERTY": 0,
        "LIABILITY_MORTGAGE_ON_RESIDENTIAL_PROPERTY_TOTAL": 0,
        "LIABILITY_MORTGAGE_ON_OTHER_PROPERTY_TOTAL": 0,
        "LIABILITY_OTHER_LOAN_TOTAL": 0,
        "LIABILITY_STUDENT_LOAN_TOTAL": 0,
        "AVAILABLE_NET_WORTH_TOTAL": -546949.8543955603,
        "NET_WORTH_TOTAL": -546949.8543955603
    },
    "30": {
        "TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": 2291.304498528221,
        "TOTAL_ASSETS_TAX_ADVANTAGED": 0,
        "TOTAL_ASSETS_PENSION": 0,
        "TOTAL_ASSETS_PHYSICAL_ASSETS": 0,
        "TOTAL_ASSETS_PROPERTY": 234671.95544404644,
        "LIABILITY_MORTGAGE_ON_RESIDENTIAL_PROPERTY_TOTAL": 0,
        "LIABILITY_MORTGAGE_ON_OTHER_PROPERTY_TOTAL": 0,
        "LIABILITY_OTHER_LOAN_TOTAL": 0,
        "LIABILITY_STUDENT_LOAN_TOTAL": 0,
        "AVAILABLE_NET_WORTH_TOTAL": 2291.3044985282177,
        "NET_WORTH_TOTAL": 236963.25994257466
    },
    "50": {
        "TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": 3599.1624268574933,
        "TOTAL_ASSETS_TAX_ADVANTAGED": 0,
        "TOTAL_ASSETS_PENSION": 0,
        "TOTAL_ASSETS_PHYSICAL_ASSETS": 0,
        "TOTAL_ASSETS_PROPERTY": 245733.8991500361,
        "LIABILITY_MORTGAGE_ON_RESIDENTIAL_PROPERTY_TOTAL": 0,
        "LIABILITY_MORTGAGE_ON_OTHER_PROPERTY_TOTAL": 0,
        "LIABILITY_OTHER_LOAN_TOTAL": 0,
        "LIABILITY_STUDENT_LOAN_TOTAL": 0,
        "AVAILABLE_NET_WORTH_TOTAL": 3599.1624268574815,
        "NET_WORTH_TOTAL": 249333.06157689358
    },
    "70": {
        "TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": 3979.852620239777,
        "TOTAL_ASSETS_TAX_ADVANTAGED": 0,
        "TOTAL_ASSETS_PENSION": 0,
        "TOTAL_ASSETS_PHYSICAL_ASSETS": 0,
        "TOTAL_ASSETS_PROPERTY": 257760.34555972004,
        "LIABILITY_MORTGAGE_ON_RESIDENTIAL_PROPERTY_TOTAL": 0,
        "LIABILITY_MORTGAGE_ON_OTHER_PROPERTY_TOTAL": 0,
        "LIABILITY_OTHER_LOAN_TOTAL": 0,
        "LIABILITY_STUDENT_LOAN_TOTAL": 0,
        "AVAILABLE_NET_WORTH_TOTAL": 3979.852620239777,
        "NET_WORTH_TOTAL": 261740.1981799598
    },
    "100": {
        "TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": 6339.55303697443,
        "TOTAL_ASSETS_TAX_ADVANTAGED": 0,
        "TOTAL_ASSETS_PENSION": 0,
        "TOTAL_ASSETS_PHYSICAL_ASSETS": 0,
        "TOTAL_ASSETS_PROPERTY": 281113.15612111986,
        "LIABILITY_MORTGAGE_ON_RESIDENTIAL_PROPERTY_TOTAL": 0,
        "LIABILITY_MORTGAGE_ON_OTHER_PROPERTY_TOTAL": 0,
        "LIABILITY_OTHER_LOAN_TOTAL": 0,
        "LIABILITY_STUDENT_LOAN_TOTAL": 0,
        "AVAILABLE_NET_WORTH_TOTAL": 6339.553036974452,
        "NET_WORTH_TOTAL": 287452.7091580943
    }
}

The keys in the payload are self explanatory.

This time series data can be used to see the evolution of the household year by yer given their circumstances.

To find the meaning of the bands (groups) the following call can be made:

curl -X GET \
  https://api.envizage.me/results/5cbf3fd34759450012b54f50/bands \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

The result will give you the bands and the description of each band (group):

{
    "content": [
        {
            "id": "5cbf40008dddb20013c5ffb1",
            "name": "Worst",
            "description": "Worst",
            "index": 1,
            "upperBound": 30,
            "lowerBound": 0
        },
        {
            "id": "5cbf40008dddb20013c5ffb2",
            "name": "Ok",
            "description": "Ok",
            "index": 2,
            "upperBound": 50,
            "lowerBound": 30
        },
        {
            "id": "5cbf40008dddb20013c5ffb3",
            "name": "Good",
            "description": "Good",
            "index": 3,
            "upperBound": 70,
            "lowerBound": 50
        },
        {
            "id": "5cbf40008dddb20013c5ffb4",
            "name": "Best",
            "description": "Best",
            "index": 4,
            "upperBound": 100,
            "lowerBound": 70
        }
    ]
}

9. Modify the mortgage type

9.1 Change the mortgage type from repayment to interest-only

In the following example the mortgage type changes.

curl -X POST \
  https://api.envizage.me/households/<household_id>/liabilities/mortgages/<liabilityId> \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json;charset=utf-8' \
  -d '{
    "id": "<liabilityId>",
    "amount": 350000,
    "balanceAmount": 0,
    "currency": "GBP",
    "startDate": "2019-04-17T16:05:30.729Z",
    "endDate": "2045-04-17T16:05:30.729Z",
    "balanceDate": "2019-04-17T16:05:30.730Z",
    "fixedRateValue": 0,
    "fixedRate": false,
    "interestOnly": true,
    "variableRateSpread": 0.05,
    "variableRateIndex": 0,
    "propertyAssetId": "<residentialPropertyId>",
    "name": "Mortgage"
}'

10. Re-run the simulation on the updated household with the pension contribution

10.1 Replace the old scenario with the new household

To re-run the scenario, first it needs to be overwritten with the data from the household.

The following call does that:

curl -X PUT \
  https://api.envizage.me/households/<household_id>/scenario/replace/<scenario_id> \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
  "id" : "<scenario_id>",
  "name" : "My scenario",
  "description" : "My scenario",
  "current" : true,
  "created" : "2019-01-01T00:00:00Z"
}'

10.2 Execute the scenario

This is exactly the same as in step 7.

curl -X GET \
  https://api.envizage.me/households/<household_id>/scenario/execute/<scenario_id> \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'resultMode: REAL'

11. Read the results and compare them with the old one

curl -X GET \
  https://api.envizage.me/results/<scenario_id>/data \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

The results will be similar format as in step 8.2, but with different values. There will be a non zero value in the pension pot which will be start paying out when the person retires funding their lifestyle after the earned income stops. This means that the household will have a greater chance covering their expenses since the pension will provide extra income. This can be seen in the balance sheet year on year.

Download Postman Workflow