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:

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.

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 -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}<YOUR_ACCESS_TOKEN>' 
    'https://api.envizage.me/households/?page=0&size=10&sort=key,asc'

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

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: