chatbot
clear chat
Skip to main content

Assess the viability of a loan to pay for a purchase

The Problem

People are usually reluctant to get a loan because they are afraid they won't be able to repay it.

A bank or other lending institutions would like for their customers to know if they can borrow to pay for a purchase and comfortably repay that loan.

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 consumer loan will have in their financial status.

For this scenario we will be focusing on a millennial couple with no kids, owning a house with a standard mortgage.

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. Set up a goal to buy a new car
  6. Create the retirement goal (mandatory)
  7. Run a simulation of the household to get a forecast of the future
  8. Read the results of the simulation
  9. Add a consumer loan
  10. Re-run the simulation on the updated household with the loan repayment
  11. Examine and compare the results.

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. Create a goal for buying the desired car

Goals are the key milestones in a household’s future plans. They represent the major aspirations of the household, and may vary over time. Envizage uses goals to mark the household wishes and it sets it up in the desired year. Each goal has a financial value and it can be financed in different ways.

The following call sets up a wish to buy a new car worth £20.000 and we wish to finance it from our savings as a first step and if necessary to get a loan for it.

curl -X POST \
https://api.envizage.me/households/<household_id>/goals/buy-a-car \
-H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"name":"Car",
"priority":5,
"frequency":"ONE_OFF",
"minimumAmount":20000,
"desiredAmount":20000,
"currency":"GBP",
"startDate":"2024-01-01T00:00:00Z",
"endDate":"2024-01-01T00:00:00Z",
"type":"BUY_A_CAR",
"fundingSources":[
{
"name":"Liquid Assets",
"class":"LiquidAssetsFundingSource",
"wrappers":[
"GENERAL_INVESTMENT_ACCOUNT",
"TAX_ADVANTAGED",
"PENSION"
]
},
{
"name":"Consumer Loan",
"class":"OtherLoanFundingSource",
"amount":20000,
"currency":"GBP",
"termYears":10,
"annualInterestRate":0.03,
"repaymentType":"PRINCIPAL_AMORTIZATION"
}
]
}'

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 examine 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": "5cc8b1788dddb20013c73b90",
"name": null,
"description": null,
"totalLives": 500,
"totalAlive": 490,
"totalAchieved": 248,
"totalNotAchieved": 242,
"goalId": "5cc8b15653734900115a486f"
}
FieldDescription
totalLivesThe number of simulations for this household.
totalAliveHow many times the primary person was alive when reaching the goal.
totalAchievedHow many times the goal was afforded.
totalNotAchievedHow 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": -543758.3577806151,
"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": -543758.3577806151,
"NET_WORTH_TOTAL": -543758.3577806151
},
"30": {
"TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": -165927.80734268852,
"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": -165927.80734268852,
"NET_WORTH_TOTAL": -165927.80734268852
},
"50": {
"TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": -102208.22826780487,
"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": -102208.22826780487,
"NET_WORTH_TOTAL": -102208.22826780487
},
"70": {
"TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": -7849.485826458316,
"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": -7849.485826458316,
"NET_WORTH_TOTAL": -7849.485826458316
},
"100": {
"TOTAL_ASSETS_SAVINGS_AND_INVESTMENTS": 267913.4208715857,
"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": 267913.4208715857,
"NET_WORTH_TOTAL": 267913.4208715857
}
}

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 Add a consumer loan

Adding a consumer loan will enable to finance the car directly because the value of the loan will be available for the household when they buy the car, which will be paid off. The loan will be repaid in 5 years.

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

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 new scenario",
"description" : "My new 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.

Taking out a loan might or might not have a positive effect on either achieving the goal or the total net-worth after the car purchase.

Download Postman Workflow