Overview

Our analytic engine powers applications that help users look into their future, understand it, and improve it.

Our engine relies on a powerful and proprietary simulation-based method that models real-world risk factors into the future. These risks affect the future aspirations of households and individuals. They are caused by Economic Risk Factors such as fluctuations in the capital markets (for example, equity and bond prices), interest rates and inflation, and also by Life Risk Factors such as mortality, longevity, health, disability, loss of an income, and long-term care.

To achieve this, our API follows these steps:

1. It enables the creation and/or authentication of Clients (for example, a specific instance of our server at a large bank) and multiple Households within each client.
2. It enables an Admin user at the Client to create and maintain all relevant reference data (such as capital markets assumptions, actuarial assumptions), system configuration, security settings, and much more.
3. For each Household, it enables the creation of one or more Scenarios that represents that user's household, together with its financial means and its future aspirations (referred to as Goals). Each scenario may be an update to the household's reality, or it may be wishful thinking (a "what if?" scenario).
4. For that scenario, it then simulates the balance sheet and income statement of the household into the future, factoring in the impact on the household of each of the sources of risk described above. It does so for a certain number of simulated lives, with the default being 500 lives, stepping into the future year by year within each life.
5. For each time step where a goal or milestone occurs, it determines whether the goal is achievable, and to what extent. If it is not achievable, it first determines, then ranks, the causes and the actions that can increase achievability.

The API allows for the creation, storage and extraction of multiple scenarios per household, together with all output data associated with each scenario and household, including a comparison of the differences between two scenarios.

The output of our analytic engine can be used in numerous ways, including but not limited to:

• educating the user on their choices and tradeoffs to address future risks
• powering a self-directed "execution-only" user journey
• powering a consistent, repeatable, auditable advice journey between advisor and customer
• designing financial products that truly improve a customer's future outcomes
• and numerous other user cases

HTTP verbs

The API adheres as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs. In particular it makes use of the following verbs:

Verb	Usage
GET	Retrieves a single or a list of resources
HEAD	Checks the existence of the resource
POST	Creates a new resource
PUT	Updates an existing resource
DELETE	Deletes an existing resource

Divergence from the REST paradigm is documented for each case.

HEAD

The request for a HEAD by resource Id is similar to that of a GET by resource Id.

For example GET https://api.envizage.me/scenarios/{scenarioId} has a corresponding HEAD https://api.envizage.me/scenarios/{scenarioId}.

If the resource with the given Id exists, the response to HEAD by resource Id contains a 204 No Content status code, and no body. If it does not, a response with a 404 Not Found status code is returned.

For conciseness only the GET by resource Id requests/responses are documented while the HEAD ones can be inferred from the above description.

HTTP status codes

The API adheres as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code	Usage
200 OK	The request completed successfully
201 Created	A new resource has been created successfully. The resource URI is available in the response header under the Location key.
204 No Content	The request completed successfully and there is no additional content.
400 Bad Request	The request either contains invalid data or it is malformed. The response body will include an error providing further information.
401 Unauthorized	The API credentials or access token used are incorrect.
403 Forbidden	The authenticated user does not have access to the requested resource or action.
404 Not Found	The requested resource does not exist.
500 Internal Server Error	There are internal or API-related errors on the server side. Additional requests will not resolve the issue.

Pagination

Pagination is used for every endpoint with a sufficiently large set of data. HTTP parameters are used as pointers to the current page and to the number of elements in a page. The previous and next sets are worked out based on the page metadata returned when pagination is requested.

Example request with Pagination

curl -X GET 'https://api.envizage.me/scenarios/?page=0&size=10&sort=key,asc' \
     -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' 

The acquisition of the access token used in the Authentication header is described in the Authentication section.

Request Param	Description
page	The 0 based index of the requested data set. The first page will have page=0.
size	The number of elements the page should contain.

Errors

If there is an error with a request, a JSON containing an error type and message will be returned.

The status will always match the returned HTTP status code. While there are unique error types and messages, most invalid request errors (400s) will either use invalid_parameter or bad_request. These messages are then used for describing the request errors such as a missing required field(s) or an improperly formatted parameter.

The below example illustrates a validation error:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 161
{
    "status": "BAD_REQUEST",
    "message": "Validation failed",
    "errors": [
        {
            "field": "currency",
            "message": "may not be null"
        },
        {
            "field": "amount",
            "message": "may not be null"
        }
    ]
}

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path	Type	Description
status	String	The HTTP status of the error response.
message	String	The error description.
errors	Array	A list of specific errors if there are more than one.