Give homeowners a compelling rationale to buy life and disability insurance when they take on a mortgage

The Problem

When taking out a mortgage, the homeowners don't necessarily think about what can happen more than 10 years in the future. A lot can change and there is always a chance of unexpected early death or disability in the household which will make the dependants unable to carry on paying the mortgage.

The Solution

Create a tool based on actuarial data that can simulate the likelihood of one or both persons dying and leaving the dependants unable to pay, can highlight the benefits of buying a life or disability insurance which will make it possible to meet any future mortgage payments in case of a tragedy.

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 income the household generates
4. Add the expenses the household incurs
5. Add a residential property and assign a mortgage to the property
6. Set up the retirement for the primary person
7. Run a simulation of current household to get a forecast of the future
8. Add a life insurance 9. Run the simulation but this time on the household with the added insurance
9. Compare the achievability score of the goals. If the achievability increases, it means that having a life insurance, increases the chances of achieving the desired lifestyle and future goals.

You can...

Change the values of the added insurance policy to find the right balance within price and benefits for the household.

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

Since we are trying to assess the impact of a term life insurance, a household with at least 2 persons need to be considered.

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 a residential property and a mortgage

We're simulating a scenario where the people in the household are new homeowners and already purchased the property with a mortgage.

5.1 Create the residential property

The following call creates a residential property

curl -X POST \
  https://api.envizage.me/households/<household_id>/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"
}'

5.2 Associate a mortgage to the property

We will use the ID of the newly created property in the following call to create a mortgage liability

curl -X POST \
  https://api.envizage.me/households/{householdId}/cb74f5f799f0100148fec86/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": "<propertyAssetId>",
    "name": "Mortgage"
}'

6. 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
  }
}'

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.

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

7.1 Obtain the scenario id

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

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. One is when one of the persons dies or becomes critically ill. Because the plans were made for both partners having an income, this is a big change. A life insurance should improve the chances. Let's see how it's done.

9. Add life term insurance

Let's add a life insurances for both persons in the household.

curl -X POST \
  https://api.envizage.me/households/<household_id>/persons/<primary_id>/insurances/life \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name" : "My life insurance",
  "payout" : 150000.0,
  "payoutCurrency" : "GBP",
  "frequency" : "ONE_OFF",
  "startDate" : "2019-01-01T00:00:00Z",
  "startsOn" : "USER_DEFINED",
  "endDate" : "2019-01-01T00:00:00Z",
  "endsOn" : "ON_RETIREMENT",
  "joint" : false
}'

curl -X POST \
  https://api.envizage.me/households/<household_id>/persons/<partner_id>/insurances/life \
  -H 'Content-Type: application/json' \
  -d '{
  "name" : "Partner life insurance",
  "payout" : 150000.0,
  "payoutCurrency" : "GBP",
  "frequency" : "ONE_OFF",
  "startDate" : "2019-01-01T00:00:00Z",
  "startsOn" : "USER_DEFINED",
  "endDate" : "2019-01-01T00:00:00Z",
  "endsOn" : "ON_RETIREMENT",
  "joint" : false
}'

10. Replace the previous scenario with the new one

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"
}'

11. 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'

12. Read the results

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

The results will be similar format as in step 8, but with different values. There should be an increase in the number of times the goals were achieved. This is the effect of the life insurance, which kicks in when a person dies, but it pays out a lump sum so the goal can still be afforded.

Download Postman Workflow