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.
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:
| Field | Description |
|---|---|
| name | The name you wish to give your scenario. |
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:
| Field | Description |
|---|---|
name | The name given to the living expense. |
frequency | This can be one of the frequencies. In this case we model monthly so it's set to MONTHLY. |
amount | The amount of the expense. |
currency | The currency in which amount is expressed. |
startDate | The start date of the living expense. |
startsOn | Can be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH. |
endDate | The end date of the living expense. |
endsOn | Can be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH. |
growthRate | Can be either of CALCULATED, NONE, CPI. |
nonDiscretionaryPercentage | Percentage of expenditure considered non-discretionary. |
survivorAdjustmentPercentage | Percentage 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:
| Field | Description |
|---|---|
name | The name given to the earned income. This can be anything, eg. My salary |
amount | The amount of the earned income. |
currency | The currency of the earned income. |
startDate | The start date of the earned income. |
endDate | The end date of the earned income. |
frequency | This can be one of the frequencies. In this case we model yearly so it's set to ANNUALLY. |
startsOn | Can be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH. |
endsOn | Can be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH. |
growthRate | Can 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:
| Field | Description |
|---|---|
name | The name given to the retirement goal. This can be anything, eg. RETIREMENT |
priority | The 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. |
frequency | This has to be ONE_OFF. |
startDate | This is the date when the retirement takes place. |
type | Must be RETIREMENT. |
properties.percentageOfPreRetirementSpendFirst10Years | The desired spend in the first 10 years after retirement expressed as a percentage of pre retirement spend |
properties.tradeDownHouse | True if the the current house is to be traded for a cheaper one to fund retirement. |
properties.tradeDownNewHousePercentage | The value of the new house to be acquired after retirement, expressed as a percentage of the property the household members live in. |
properties.tradeDownDate | Date in which the property should be traded down |
properties.percentageOfSurvivorExpenditureSpend | The desired spend after retirement in the situation when the partner has died, expressed as a percentage of pre retirement spend. |
properties.percentageOfPreRetirementSpendAfterFirst10Years | The 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.