chatbot
clear chat
Skip to main content

Workflows-Basic

Getting Started

The Envizage API

The base URL https://api.envizage.me is meant to be used for all API requests.

Curly braces { } represent variables and they are not to be included in the actual request, but are to be replaced by actual values instead.

note

The following are provided as sample workflows and are by no means comprehensive. The API catalog sections of this documentation contains the details of each call.

Obtain API user credentials

The API user credentials consist of a client-id and a client-secret. They can be obtained by connecting a new backend application at the Developer Console url. Login with the newly created account and the API credentials can be seen and managed in the Back-End connection section of your Applications page.

Having the realm, client ID and client secret values we will see in the workflows how to create a user and obtain a user access token which is required in order to utilize the Envizage API.

Postman

The workflows in this section have been created in Postman. See how to run Postman in Subsection using Postman with the API here. Initially, setup in the environment or as global variables the base url and the obtained `client-id` and `client-secret`, i.e, api_url=api.envizage.me, auth_url=id.production.envizage.me, clientId=<OBTAINED_CLIENT_ID>, clientSecret=<OBTAINED_CLIENT_SECRET>.

The basic workflow in Postman can be downloaded here.

The workflow can also be run in the command-line with newman. Execute the following, after editing the credentials and the path to workflow.

newman --global-var "api_url=api.envizage.me" --global-var "auth_url=id.production.envizage.me" --global-var "realm=<OBTAINED_REALM>"  --global-var "clientId=<OBTAINED_CLIENT_ID>" --global-var "clientSecret=<OBTAINED_CLIENT_SECRET>" run <path to workflow>/envizage.workflow.basic.json

1. Get Service Access Token

The service access token is used in to create, update or delete a user. The following request shows how to obtain it.

curl -X POST "https://id.production.envizage.me/realms/{OBTAINED_REALM}/protocol/openid-connect/token" \
-d "grant_type=client_credentials" \
-d "client_id=<OBTAINED_CLIENT_ID>" \
-d "client_secret=<OBTAINED_CLIENT_SECRET>"

Sample Response Body:

{
"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJwSWxNNUxSUGw5clNaWnVFdkdGMUNFcVJQcWZTeGtKaWNUT0I1Y3dNdFBNIn0.eyJleHAiOjE2ODgzNzA5MTMsImlhdCI6MTY4ODM3MDYxMywianRpIjoiOGU1NDc2OGYtYjZjNi00NGQ4LWJjYjctYmRjMWIwYzNjNTQzIiwiaXNzIjoiaHR0cHM6Ly9pZC5hbHBoYS5lbnZpemFnZS5tZS9yZWFsbXMvNTU5Y2EwNzktMzRmMS00MGM1LWE2ZDUtN2IzZDgxYjhhNzI1IiwiYXVkIjpbInJlYWxtLW1hbmFnZW1lbnQiLCJhY2NvdW50Il0sInN1YiI6Ijg0NGU2NTA2LTUyYmQtNDQyMC05YjBiLTZhZTQ3YWM2NDA3ZCIsInR5cCI6IkJlYXJlciIsImF6cCI6ImI0YWNhMTM2LWU4ZmYtNGE2OC04YzQwLWU4ODYwMTQ3MmJkNiIsImFsbG93ZWQtb3JpZ2lucyI6W10sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJyb2xlX2FociIsInJvbGVfYWh3Iiwicm9sZV9hcnIiLCJyb2xlX3J1IiwiZGVmYXVsdC1yb2xlcy01NTljYTA3OS0zNGYxLTQwYzUtYTZkNS03YjNkODFiOGE3MjUiXX0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm1hbmFnZS11c2VycyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcmVmZXJlbmNlcy51c2VyOnJlYWQgcHJlZmVyZW5jZXMudXNlcjp3cml0ZSBzY2VuYXJpb3M6ZnVsbCByZXN1bHRzOnJlYWQgcHJlZmVyZW5jZXMuY2xpZW50OnJlYWQgY29tcGxpYW5jZTpnZXQtbXktZGF0YSIsImNsaWVudEhvc3QiOiIyMDkuMzUuMjI0LjgiLCJjbGllbnRJZCI6ImI0YWNhMTM2LWU4ZmYtNGE2OC04YzQwLWU4ODYwMTQ3MmJkNiIsInJlYWxtIjoiNTU5Y2EwNzktMzRmMS00MGM1LWE2ZDUtN2IzZDgxYjhhNzI1IiwiY2xpZW50QWRkcmVzcyI6IjIwOS4zNS4yMjQuOCIsImNsaWVudF9pZCI6IjU1OWNhMDc5LTM0ZjEtNDBjNS1hNmQ1LTdiM2Q4MWI4YTcyNSJ9VIAuNBCN4NFoSyW54nZElSNZRon_Cf2zIxUbaRuVmHmC3eLZ1QWnTN812FbW6cGvicO-kK7IwQpsUHlJbkWh9wl01t-rfAfcWnW2unatunZz3XP7gISLDdIdPqvcEvPUYCMd8IrnSwmEDuM6ao9xpBn4kAsdmD0KAgN7eU81YMcvq03tJyrR2KbR7gHrO6bm5qtfe-jlWlRf2XOKFLPl9uNF-iJ40TZcmpw-PxJQltIavq3WOUHU6qBjZjiRdtoX_qz-RpjwPdJRG5kHMxLfX9YXp4egvNLIxCcspypwWQYt0cHGPY_-RvtoU_hmQGSAr1SBLYjb7ISDiqkEnT6FQg",
"expires_in":300,
"refresh_expires_in":0,
"token_type":"Bearer",
"not-before-policy":0,
"scope":"preferences.user:read preferences.user:write scenarios:full results:read preferences.client:read compliance:get-my-data"
}

2. Create a User

Create a user by using the service access token from the previous step. By having a user, you can request and get a user access token. The following request shows how to create a user.

curl -X POST "https://id.production.envizage.me/admin/realms/{REALM}/users" \
-H 'Content-Type: application/json;charset=UTF-8' \
-H "Authorization: Bearer <YOUR_SERVICE_ACCESS_TOKEN>" \
-d '{
"username": "<USERNAME>",
"email": "<EMAIL>",
"firstName": "<FIRST_NAME>",
"lastName": "<LAST_NAME>",
"enabled": true,
"emailVerified": true,
"credentials": [
{
"type": "password",
"value": "<PASSWORD>"
}
]
}

3. Get User Access Token

The user access token is used in order to utilize the Envizage API and should be passed through header of every request. User's username and password, as well as client id and client secret, are mandatory to get the user access token. 'Grant_type' parameter must set to 'password'. The request below is an example of how to obtain the user access token.

curl -X POST "https://id.production.envizage.me/realms/{REALM}/protocol/openid-connect/token" \
-d "username=<USERNAME>&password=<PASSWORD>&grant_type=password&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>"

4. Create a New Scenario

Having the user access token from previous step, you can communicate and use the Envizage API. The subject of the simulation is the household which is grouped under a scenario.

curl 'https://api.envizage.me/scenarios/' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>" \
-d '{
"name" : "My Scenario",
"description" : "My primary scenario"
}'

Sample Response Body:

{  
"id": "{scenarioId}",
"name": "My Scenario",
"description": "My primary scenario"
}

Send a `POST` request to https://api.envizage.me/scenarios.

Pass your access token as a bearer authorization header, i.e., Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>.

In the request body, send:

FieldDescription
nameThe name you wish to give your scenario.
note

Note the id of your newly created Scenario. In our example it’s 5c6aecbcd891750010329714.

Save the returned ID as it will have to be part of any subsequent request.

At this step also a Primary Person is created as there has to be exactly one primary person in the household. We can not create another one or delete the existing. Furthermore, there can be zero or one partners and zero or multiple children and parents in the household.

5. Create Monthly Living Expenses

curl 'https://api.envizage.me/scenarios/{scenarioId}/expenses/living' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>" \
-d '{
"name" : "My living expense",
"frequency" : "MONTHLY",
"amount" : 2200,
"currency" : "GBP",
"startDate" : "2021-01-01T00:00:00Z",
"startsOn" : "USER_DEFINED",
"endDate" : "2021-01-01T00:00:00Z",
"endsOn" : "ON_DEATH",
"growthRate" : "CALCULATED",
"nonDiscretionaryPercentage" : 0.75,
"survivorAdjustmentPercentage" : 0.75
}'

Sample Response Body:

{  
"id": "5c795d9bd8917500103f3aa0",
"name": "My living expense",
"description": null,
"source": null,
"frequency": "MONTHLY",
"amount": 2200.0,
"currency": "GBP",
"startDate": "2021-01-01T00:00:00Z",
"startsOn": "USER_DEFINED",
"endDate": "2221-02-18T15:08:56.727Z",
"endsOn": "ON_DEATH",
"growthRate": "CALCULATED",
"spreadOverGrowthRate": null,
"nonDiscretionaryPercentage": 0.75,
"survivorAdjustmentPercentage": 0.75
}

To set up monthly expenses for the household send a `POST` request to https://api.envizage.me/scenarios/{scenarioId}/expenses/living.

The {scenarioId} needs to be replaced with the returned Scenario's Id.

In the payload send:

FieldDescription
nameThe name given to the living expense.
frequencyThis can be one of the frequencies. In this case we model monthly so it's set to MONTHLY.
amountThe amount of the expense.
currencyThe currency in which amount is expressed.
startDateThe start date of the living expense.
startsOnCan be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH.
endDateThe end date of the living expense.
endsOnCan be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH.
growthRateCan be either of CALCULATED, NONE, CPI.
nonDiscretionaryPercentagePercentage of expenditure considered non-discretionary.
survivorAdjustmentPercentagePercentage of expenditure for the surviving partner.

6. Get Primary Person

curl 'https://api.envizage.me/scenarios/{scenarioId}/persons/primary' -i \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>"

Sample Response Body:

{  
"id": "5c795d1fd8917500103f3a90",
"name": "Me",
"description": null,
"lastName": null,
"yearOfBirth": 1981,
"primary": true,
"gender": "MALE",
"maritalStatus": "UNSPECIFIED",
"healthStatus": "EXCELLENT",
"jobType": "ACTIVE",
"expectedRetirementAge": 67
}

To get the details of the primary person from the household send a `GET` request to https://api.envizage.me/scenarios/{scenarioId}/persons/primary.

Save the primary person id, i.e., 5c6aecbcd891750010329718 as it is needed in order to associate various household entities (income, expenses, liabilities, insurances etc) with the primary person.

The result is a person named Me with values defaulted by the system. This person's attributes need to be updated to reflect the real life circumstances.

7. Create Annual Earned Income (Salary)

curl 'https://api.envizage.me/scenarios/{scenarioId}/persons/{personId}/c795d1fd8917500103f3a90/incomes/earned' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>" \
-d '{
"name" : "My earned income",
"frequency" : "ANNUALLY",
"amount" : 70000.0,
"currency" : "GBP",
"startDate" : "2021-01-01T00:00:00Z",
"startsOn" : "USER_DEFINED",
"endDate" : "2040-01-01T00:00:00Z",
"endsOn" : "ON_RETIREMENT",
"growthRate" : "CALCULATED"
}'

Sample Response Body:

{  
"id": "5c795e04d8917500103f3ab0",
"name": "My earned income",
"description": null,
"source": null,
"frequency": "ANNUALLY",
"amount": 70000.0,
"currency": "GBP",
"startDate": "2021-01-01T00:00:00Z",
"startsOn": "USER_DEFINED",
"endDate": "2048-01-01T00:00:00Z",
"endsOn": "ON_RETIREMENT",
"growthRate": "CALCULATED",
"spreadOverGrowthRate": null,
"maximumAbsoluteSpreadAllowed": null
}

To set up an earned income for the primary person send a `POST` request to https://api.envizage.me/scenarios/{scenarioId}/persons/{primaryPersonId}/incomes/earned.

The {scenarioId} needs to be replaced with the Scenario's ID.

The {primaryPersonId} needs to be replaced with the Primary Person's ID.

In the payload send:

FieldDescription
nameThe name given to the earned income. This can be anything, eg. My salary
amountThe amount of the earned income.
currencyThe currency of the earned income.
startDateThe start date of the earned income.
endDateThe end date of the earned income.
frequencyThis can be one of the frequencies. In this case we model yearly so it's set to ANNUALLY.
startsOnCan be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH.
endsOnCan be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH.
growthRateCan be either of CALCULATED, NONE, CPI

8. Create the Retirement Goal

The retirement goal is an important milestone in the simulation.

curl 'https://api.envizage.me/scenarios/{scenarioId}/goals/typed' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>" \
-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": "2048-01-01T00:00:00Z",
"tradeDownHouse": false,
"tradeDownNewHousePercentage": 1
}
}'

Sample Response Body:

{  
"id": "5c795e35558af400101c3372",
"name": "Retirement",
"description": null,
"priority": 5,
"frequency": "ONE_OFF",
"minimumAmount": 0,
"desiredAmount": 0,
"currency": "USD",
"startDate": "2048-01-01T00:00:00Z",
"startsOn": "USER_DEFINED",
"endDate": "2048-01-01T00:00:00Z",
"endsOn": "USER_DEFINED",
"fundingSources": [
{
"class": "LiquidAssetsFundingSource",
"name": "Liquid Assets",
"description": null,
"wrappers": [
"GENERAL_INVESTMENT_ACCOUNT",
"TAX_ADVANTAGED",
"PENSION"
],
"id": "5c795e35558af400101c3373"
}
],
"type": "RETIREMENT",
"properties": {
"percentageOfPreRetirementSpendFirst10Years": 1.0,
"tradeDownDate": "2048-01-01T00:00:00Z",
"tradeDownNewHousePercentage": 1.0,
"tradeDownHouse": false,
"percentageOfSurvivorExpenditureSpend": 1.0,
"percentageOfPreRetirementSpendAfterFirst10Years": 1.0
}
}

Send a `POST` request to https://api.envizage.me/scenarios/{scenarioId}/goals/typed.

The {scenarioId} needs to be replaced with the Scenario's ID.

In the payload send:

FieldDescription
nameThe name given to the retirement goal. This can be anything, eg. RETIREMENT
priorityThe priority with which this goal will be treated. We encourage using a scale between 1-10, however there is no limit, the higher the number the higher the priority of the goal. It's relative to the other goals' priorities.
frequencyThis has to be ONE_OFF.
startDateThis is the date when the retirement takes place.
typeMust be RETIREMENT.
properties.percentageOfPreRetirementSpendFirst10YearsThe desired spend in the first 10 years after retirement expressed as a percentage of pre retirement spend
properties.tradeDownHouseTrue if the the current house is to be traded for a cheaper one to fund retirement.
properties.tradeDownNewHousePercentageThe value of the new house to be acquired after retirement, expressed as a percentage of the property the household members live in.
properties.tradeDownDateDate in which the property should be traded down
properties.percentageOfSurvivorExpenditureSpendThe desired spend after retirement in the situation when the partner has died, expressed as a percentage of pre retirement spend.
properties.percentageOfPreRetirementSpendAfterFirst10YearsThe desired spend after 10 years of retirement expressed as a percentage of pre retirement spend.

The response contains the liquid assets funding source, as it is, by default, added to a goal for which no funding source has been specified. It has no impact on the retirement goal calculations.

9. Get Default Scenario

A scenario contains a household. It can be executed causing a simulation to run. Next we request the default scenario. We can obtain its id and use it to execute the scenario.

curl 'https://api.envizage.me/scenarios/{scenarioId}' -i \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>"

Sample Response Body:

{  
"content":[
{
"id": "5c795d1fd8917500103f3a92",
"name": "Me Today",
"description": null,
"current": true,
"created": "2021-03-01T16:26:07.747Z",
"household": {
"class": "Household",
"name": "My Household",
"description": "My primary household",
"preferences": {
"modelling.default.data.asset.allocation.unrealized.or.negative.class": "cash",
"user.input.partner.year.of.birth": 1981,
"user.default.data.income.pension.state.partner.started.work.at.age": 22,
"simulation.parameter.savings.sequence": [
{
"id": "isa",
"name": "Individual Savings Account Savings",
"description": "Individual Savings Account Savings",
"wrapper": "isa",
"annualCap": 20000,
"lifetimeCap": 0,
"active": false
}
],
"modelling.default.data.asset.allocation.presets.matrix":{
"low": [
0.54,
0.07,
0.09,
0.07,
0.19,
0.04,
0.0,
0.0,
0.0
],
"medium-low": [
0.24,
0.07,
0.15,
0.12,
0.34,
0.08,
0.0,
0.0,
0.0
],
"moderate": [
0.12,
0.05,
0.12,
0.15,
0.45,
0.11,
0.0,
0.0,
0.0
],
"medium-high": [
0.06,
0.03,
0.08,
0.14,
0.54,
0.15,
0.0,
0.0,
0.0
],
"high": [
0.04,
0.02,
0.05,
0.12,
0.58,
0.19,
0.0,
0.0,
0.0
]
},
"user.input.goal.car.amount": 16000,
"user.input.goal.house.amount": 219000,
"user.input.goal.house.mortgage.of.value.percent": 0.83,
"user.input.goal.child.amount": 9900,
"user.input.user.gender": "FEMALE",
"user.input.goal.school.year.offset": 1,
"user.default.data.income.pension.state.primary.started.work.at.age": 22,
"user.input.goal.married.amount": 22700,
"modelling.default.data.asset.allocation.unrealized.or.negative.wrapper": "general_investment_account",
"user.input.goal.debt.amount": 44000,
"user.default.data.asset.retirement.age.partner": 67,
"user.input.goal.school.amount": 15000,
"user.input.user.year.of.birth": 1981,
"modelling.default.data.asset.allocation.matrix": {
"general.investment.account": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"isa": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"ESDCS": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"sipp": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0
]
},
"user.default.data.asset.retirement.age.primary": 67,
"user.input.goal.travel.amount": 1400,
"user.input.goal.private.school.amount": 142000
},
"initialized": true,
"persons": [
{
"class": "Person",
"name": "Me",
"description": null,
"lastName": null,
"yearOfBirth": 1981,
"primary": true,
"gender": "MALE",
"maritalStatus": "UNSPECIFIED",
"healthStatus": "EXCELLENT",
"jobType": "ACTIVE",
"expectedRetirementAge": 67,
"incomes": [
{
"class": "EarnedIncome",
"name": "My earned income",
"description": null,
"source": null,
"startDate": "2021-01-01T00:00:00Z",
"startsOn": "USER_DEFINED",
"endDate": "2048-01-01T00:00:00Z",
"endsOn": "ON_RETIREMENT",
"frequency": "ANNUALLY",
"amount": "GBP70,000.00",
"growthRate": "CALCULATED",
"spreadOverGrowthRate": null,
"maximumAbsoluteSpreadAllowed": null,
"id": "5c795e04d8917500103f3ab0"
}
],
"id": "5c795d1fd8917500103f3a90"
}
],
"generations": [
{
"class": "Generation",
"name": "Primary generation",
"description": null,
"active": true,
"persons": [
{
"class": "Person",
"name": "Me",
"description": null,
"lastName": null,
"yearOfBirth": 1981,
"primary": true,
"gender": "MALE",
"maritalStatus": "UNSPECIFIED",
"healthStatus": "EXCELLENT",
"jobType": "ACTIVE",
"expectedRetirementAge": 67,
"id": "5c795d1fd8917500103f3a90"
}
],
"expenses": [
{
"class": "LivingExpense",
"name": "My living expense",
"description": null,
"source": null,
"startDate": "2021-01-01T00:00:00Z",
"startsOn": "USER_DEFINED",
"endDate": "2221-02-18T15:08:56.727Z",
"endsOn": "ON_DEATH",
"frequency": "MONTHLY",
"amount": "GBP2,200.00",
"growthRate": "CALCULATED",
"spreadOverGrowthRate": null,
"nonDiscretionaryPercentage": 0.75,
"survivorAdjustmentPercentage": 0.75,
"id": "5c795d9bd8917500103f3aa0"
}
],
"goals":[
{
"class": "RetirementGoal",
"name": "Retirement",
"description": null,
"source": null,
"startDate": "2048-01-01T00:00:00Z",
"startsOn": "USER_DEFINED",
"endDate": "2048-01-01T00:00:00Z",
"endsOn": "USER_DEFINED",
"priority": 5,
"frequency": "ONE_OFF",
"discretionary": false,
"minimumAmount": "USD0.00",
"desiredAmount": "USD0.00",
"fundingSources": [
{
"class": "LiquidAssetsFundingSource",
"name": "Liquid Assets",
"description": null,
"wrappers": [
"GENERAL_INVESTMENT_ACCOUNT",
"TAX_ADVANTAGED",
"PENSION"
],
"id": "5c795e35558af400101c3373"
}
],
"percentageOfPreRetirementSpendFirst10Years": 1.0,
"percentageOfPreRetirementSpendAfterFirst10Years": 1.0,
"percentageOfSurvivorExpenditureSpend": 1.0,
"tradeDownHouse": false,
"tradeDownNewHousePercentage": 1.0,
"tradeDownDate": "2048-01-01T00:00:00Z",
"id": "5c795e35558af400101c3372"
}
],
"id": "5c795d1fd8917500103f3a8d"
},
{
"class": "Generation",
"name": "Older generation",
"description": null,
"active": false,
"id": "5c795d1fd8917500103f3a8e"
},
{
"class": "Generation",
"name": "Younger generation",
"description": null,
"active": false,
"id": "5c795d1fd8917500103f3a8f"
}
],
"id": "{scenarioId}"
}
}
],
"totalPages": 1,
"totalElements": 1,
"last": true,
"sort": null,
"numberOfElements": 1,
"first": true,
"size": 20,
"number": 0
}

To get the current scenario for the household send a `GET` request to https://api.envizage.me/scenarios/{scenarioId}/scenario.

The {scenarioId} needs to be replaced with the returned Scenario's ID.

In the response the content[0].id is the scenario ID, i.e., 5c6aecbcd89175001032971a. Save it in order to use it to execute this scenario.

10. Execute Scenario

curl 'https://api.envizage.me/scenarios/{scenarioId}/execute' -i -X POST \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>" \
-d '[
[{
"dataset": "goal",
"aggregate": "goalId",
"name": "ta",
"bands": {
"cell": "BS@NET_WORTH@TOTAL",
"percentiles": [0, 20, 50, 80, 100]
}
}, {
"achieved": 1
}, {
"totalAchieved": {
"$count": 1
}
}],
[{
"dataset": "goal",
"aggregate": "goalId",
"name": "el",
"bands": {
"cell": "BS@NET_WORTH@TOTAL",
"percentiles": [0, 20, 50, 80, 100]
}
}, {
"GP@eitherAlive": 1
}, {
"eitherAlive": {
"$count": 1
}
}]
]'

To execute the simulation send a `POST` request to https://api.envizage.me/scenarios/{scenarioId}/scenario/execute.

The payload of the request follows the syntax of the Envizage Query Language and is a request to get the Overall Goal Achievability.

The {scenarioId} needs to be replaced with the current Scenario's ID.

The resulting 200 Status Code signals that the scenario was dispatched for execution.

11. Get Overall Goal Achievability

curl 'https://api.envizage.me/results/{scenarioId}/query/results' -i \
-H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

Sample Response Body:

{
"id": "60ed43e0a3d2d738a56103d7",
"scenarioId": "60ed43a7a9c51358a76b8381",
"simulationId": "12d7c8ac-506c-4deb-aba2-e6ae86ad7bd5",
"clientId": "bd282389-72e1-417a-b4c0-8a23ee61679e",
"username": "3202f14c-ebae-456d-806c-a211d3e62707",
"results": [
{
"name": "ta",
"results": []
},
{
"name": "el",
"results": [
{
"goalId": "60ed43b03aae6a3e7d60846c",
"data": {
"eitherAlive": 498,
"bands": {
"1": {
"eitherAlive": 99
},
"2": {
"eitherAlive": 150
},
"3": {
"eitherAlive": 150
},
"4": {
"eitherAlive": 99
}
}
}
}
]
}
]
}

To get the overall goal achievability results send a `GET` request to https://api.envizage.me/results/{scenarioId}/query/results.

The {scenarioId} needs to be replaced with the current Scenario's ID.

12. Diagnose goal

curl 'https://api.envizage.me/scenarios/{scenarioId}/diagnose/{goalId}' -i -X POST \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>" \
-d '[
[{
"dataset": "goal",
"aggregate": "goalId",
"name": "tl",
"run": "EXPENSE_LIVING_EXPENSES_DECREASE"
}, {
"GP@eitherAlive": 1
}, {
"totalAlive": {
"$count": 1
},
"metadata": 1
}],
[{
"dataset": "goal",
"aggregate": "goalId",
"name": "tl",
"run": "EXPENSE_MORTGAGE_ON_RESIDENTIAL_PROPERTY_VS_RENT"
}, {
"GP@eitherAlive": 1
}, {
"totalAlive": {
"$count": 1
},
"metadata": 1
}],
[{
"dataset": "goal",
"aggregate": "goalId",
"name": "tl",
"run": "GOAL_SPEND_LESS_MONEY_ON_GOAL"
}, {
"GP@eitherAlive": 1
}, {
"totalAlive": {
"$count": 1
},
"metadata": 1
}],
[{
"dataset": "goal",
"aggregate": "goalId",
"name": "tl",
"run": "GOAL_MOVE_IT_TO_THE_FUTURE"
}, {
"GP@eitherAlive": 1
}, {
"totalAlive": {
"$count": 1
},
"metadata": 1
}],
[{
"dataset": "goal",
"aggregate": "goalId",
"name": "tl",
"run": "INCOME_WORK_PART_TIME_AFTER_RETIREMENT_PRIMARY"
}, {
"GP@eitherAlive": 1
}, {
"totalAlive": {
"$count": 1
},
"metadata": 1
}]
]'

To execute the goal diagnostic send a `POST` request to https://api.envizage.me/scenarios/{scenarioId}/diagnose/{goalId}.

The payload of the request follows the syntax of the Envizage Query Language and is a request to get the Overall Goal Achievability for various diagnostic runs.

The {scenarioId} needs to be replaced with the current Scenario's ID and the {goalId} needs to be replaced with the Goal's ID we want to diagnose.

The resulting 200 Status Code signals that the goal diagnose was dispatched for execution.

13. Get Diagnose Goal Results

curl 'https://api.envizage.me/results/{scenarioId}/query/diagnostics/goal/{goalId}?diagnosticTypes=EXPENSE_LIVING_EXPENSES_DECREASE,EXPENSE_MORTGAGE_ON_RESIDENTIAL_PROPERTY_VS_RENT,GOAL_SPEND_LESS_MONEY_ON_GOAL,GOAL_MOVE_IT_TO_THE_FUTURE,INCOME_WORK_PART_TIME_AFTER_RETIREMENT_PRIMARY' -i \
-H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>'

Sample Response Body:

{
"content": [
{
"id": "60ed44a8a3d2d738a5610448",
"scenarioId": "60ed43a7a9c51358a76b8381",
"simulationId": "7a4ffe7e-c07e-46d5-a5f1-f207d1e38e8b",
"clientId": "bd282389-72e1-417a-b4c0-8a23ee61679e",
"username": "3202f14c-ebae-456d-806c-a211d3e62707",
"goalId": "60ed43b03aae6a3e7d60846c",
"diagnosticType": "INCOME_WORK_PART_TIME_AFTER_RETIREMENT_PRIMARY",
"results": [
{
"name": "tl",
"results": [
{
"goalId": "60ed43b03aae6a3e7d60846c",
"data": {
"metadata": {
"WORK_PART_TIME_AFTER_RETIREMENT_MAX_AGE": 80,
"WORK_PART_TIME_AFTER_RETIREMENT_PERCENTAGE": 0.5
},
"totalAlive": 498
}
}
]
}
]
},
{
"id": "60ed44a9c32fea1b6e9c6503",
"scenarioId": "60ed43a7a9c51358a76b8381",
"simulationId": "cb4b051d-af78-491a-9d12-07f38daa0b31",
"clientId": "bd282389-72e1-417a-b4c0-8a23ee61679e",
"username": "3202f14c-ebae-456d-806c-a211d3e62707",
"goalId": "60ed43b03aae6a3e7d60846c",
"diagnosticType": "EXPENSE_MORTGAGE_ON_RESIDENTIAL_PROPERTY_VS_RENT",
"results": [
{
"name": "tl",
"results": []
}
]
},
{
"id": "60ed44a9a3d2d738a561044a",
"scenarioId": "60ed43a7a9c51358a76b8381",
"simulationId": "d7d127a0-7df2-4688-8fd8-14519eb5eb3a",
"clientId": "bd282389-72e1-417a-b4c0-8a23ee61679e",
"username": "3202f14c-ebae-456d-806c-a211d3e62707",
"goalId": "60ed43b03aae6a3e7d60846c",
"diagnosticType": "GOAL_SPEND_LESS_MONEY_ON_GOAL",
"results": [
{
"name": "tl",
"results": [
{
"goalId": "60ed43b03aae6a3e7d60846c",
"data": {
"metadata": {
"AMOUNT_PERCENTAGE": 0.9
},
"totalAlive": 498
}
}
]
}
]
},
{
"id": "60ed44a9c32fea1b6e9c6505",
"scenarioId": "60ed43a7a9c51358a76b8381",
"simulationId": "35ff0a5a-4446-4a84-bfe6-64a04b5c6259",
"clientId": "bd282389-72e1-417a-b4c0-8a23ee61679e",
"username": "3202f14c-ebae-456d-806c-a211d3e62707",
"goalId": "60ed43b03aae6a3e7d60846c",
"diagnosticType": "GOAL_MOVE_IT_TO_THE_FUTURE",
"results": [
{
"name": "tl",
"results": [
{
"goalId": "60ed43b03aae6a3e7d60846c",
"data": {
"metadata": {
"MOVE_IT_TO_THE_FUTURE_YEARS": 3
},
"totalAlive": 497
}
}
]
}
]
},
{
"id": "60ed44a9a3d2d738a561044c",
"scenarioId": "60ed43a7a9c51358a76b8381",
"simulationId": "3b6e11a1-2813-4337-a187-6e9f9354cef4",
"clientId": "bd282389-72e1-417a-b4c0-8a23ee61679e",
"username": "3202f14c-ebae-456d-806c-a211d3e62707",
"goalId": "60ed43b03aae6a3e7d60846c",
"diagnosticType": "EXPENSE_LIVING_EXPENSES_DECREASE",
"results": [
{
"name": "tl",
"results": [
{
"goalId": "60ed43b03aae6a3e7d60846c",
"data": {
"metadata": {
"AMOUNT_PERCENTAGE": 0.9
},
"totalAlive": 498
}
}
]
}
]
}
],
"pageable": {
"sort": {
"unsorted": true,
"sorted": false,
"empty": true
},
"pageSize": 20,
"pageNumber": 0,
"offset": 0,
"paged": true,
"unpaged": false
},
"totalPages": 1,
"last": true,
"totalElements": 5,
"sort": {
"unsorted": true,
"sorted": false,
"empty": true
},
"numberOfElements": 5,
"first": true,
"size": 20,
"number": 0,
"empty": false
}

To get the diagnostic results send a `GET` request to https://api.envizage.me/results/{scenarioId}/query/diagnostics/goal/{goalId}?diagnosticTypes={comma-separated-diagnostics}.

The {scenarioId} needs to be replaced with the current Scenario's ID.

The {goalId} needs to be replace with the Goal ID we want to diagnose.

The {comma-separated-diagnostics} needs to be replaced with the diagnostic runs used in the query expression of the Diagnose Goal.