Assess the Impact of a Life Insurance in a Household

The Problem

It's very difficult and time-consuming for Insurance Agents to easily pick the right policy for the members of a household.

The Solution

Create a user friendly, easy to follow application which captures all the necessary details about a household, the future goals of the household and calculates the impact different types of insurances have on achieving the desired goals.

The Flow

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

1. Create an uninsured 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
6. Add all the debts the household owns
7. Setting up individual and joint goals for the persons in the household which describe the lifestyle they want to have in the future and what's important to them
8. Run a simulation of current household to get a forecast of the future
9. Add a term life insurance to the household
10. Run the simulation but this time on the household with the added insurance
11. 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 all the assets for the household

The persons in the household might posses things of value that can be converted into cash.

Personal assets include:

• Cash and cash equivalents, certificates of deposit, checking, and savings accounts, money market accounts, physical cash, Treasury bills
• Property or land and any structure that is permanently attached to it
• Personal property – boats, collectibles, household furnishings, jewelry, vehicles
• Investments – annuities, bonds, the cash value of life insurance policies, mutual funds, pensions, retirement plans, (IRA, 401(k), 403(b), etc.) stocks

5.1 Savings the household accumulated

It's very common for a household to save money for the future. This money can be kept in a variety of accounts, like ISAs or GIAs in the UK.

We are going to add the savings to a General Investment Account and we want them to be held as Cash.

To obtain the supported Tax Wrappers and Asset Classes, we will make two calls and save the IDs of the chosen wrapper and asset class.

Get the supported/configured tax wrappers:

curl -X GET \
  https://api.envizage.me/households/reference/assets/financial/wrappers \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

Get the supported asset classes:

curl -X GET \
  https://api.envizage.me/households/reference/assets/financial/classes \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

Once the results are parsed, we will make the following call to set up savings account:

curl -X POST \
  https://api.envizage.me/households/<household_id>/assets/financial/ \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'content-type: application/json;charset=UTF-8' \
  -d '{
    "pot": "Savings",
    "value": 3000,
    "currency": "USD",
    "country": "UK",
    "assetClass": "cash",
    "wrapper": "general_investment_account",
    "institution": "generic",
    "valuationDate": "2019-04-15T15:41:13.742Z"
}'

6. Add all the debts the household owns

For a household it is also common to have some sort of debt, which can be of two types: Secured and Unsecured.

Secured debt is debt that is backed by some type of collateral such as an asset or revenue from the borrower. Secured debt is typically encountered when a large ticket item such as a house or a vehicle is purchased. Mortgages and car loans are two examples of secured debts.

Unsecured debt is a loan that is not backed by an underlying asset. Unsecured debt includes credit card debt, medical bills, utility bills and other types of loans or credit that were extended without a collateral requirement.

It's worth noting the only supported Secured debt is the Mortgage.

6.1 Set up a personal credit card loan

The following call will set up a credit card loan worth of 3.500$ with an interest rate of 5%.

curl -X POST \
  https://api.envizage.me/households/<household_id>/liabilities/unsecured-debts/ \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'content-type: application/json;charset=UTF-8' \
  -d '{
    "amount": 3500,
    "currency": "USD",
    "startDate": "2019-04-15T16:07:30.849Z",
    "endDate": "2020-01-01T00:00:00Z",
    "termYears": 0,
    "annualAverageInterestRate": 0.05,
    "repaymentType": "PRINCIPAL_AMORTIZATION",
    "name": "Credit card loan"
}'

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

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

7.2 Create a "Buy a House" Goal

Getting onto the property ladder is a very common wish amongst young couples. To model it, we will create a goal with the characteristics of the house the couple wishes to buy.

The following example puts a house worth £400.000 on the household's wish-list to be purchased in 2026 with a desired mortgage of £250.000, having the rate 3% and the term set to 20 years.

curl -X POST \
  https://api.envizage.me/households/<household_id>/goals/typed \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{  
   "name":"House",
   "priority":5,
   "frequency":"ONE_OFF",
   "minimumAmount":400000,
   "desiredAmount":400000,
   "currency":"GBP",
   "startDate":"2026-01-01T00:00:00Z",
   "endDate":"2026-01-01T00:00:00Z",
   "type":"BUY_A_HOUSE",
   "fundingSources":[  
      {  
         "name":"Liquid Assets",
         "class":"LiquidAssetsFundingSource",
         "wrappers":[  
            "GENERAL_INVESTMENT_ACCOUNT",
            "TAX_ADVANTAGED",
            "PENSION"
         ]
      },
      {  
         "name":"Mortgage",
         "class":"MortgageFundingSource",
         "amount":250000,
         "currency":"GBP",
         "termYears":20,
         "annualInterestRate":0.03,
         "repaymentType":"PRINCIPAL_AMORTIZATION",
         "mortgageType":"FIXED_AMORTIZING"
      }
   ]
}'

8. 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:

8.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.

8.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.

9. 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.

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

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

12. Execute the scenario

This is exactly the same as in step 8.

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'

13. 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 9, 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