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:
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:
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.
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.
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 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.
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.
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 |
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 |