NAV
curl javascript

Introduction

Welcome to the Openmarkets Advice API (formerly Investfit)!

We’re working hard to make it as easy as possible for you to get started using Advice as a service from within your application. We’re honoured you’re looking at partnering with us and want to do all we can to assist.

If you come across any issues while accessing the API or have suggestions on how we could improve, please submit a ticket for prioriry support at Create Support Ticket.

In this document we’re going to give you an overview of how the whole system hangs together. For detailed attributes, data models and information please refer to the links throughout this document.

Now… let’s get stuck in… you should be up and running and ready to make your first call in a few minutes!

Terminology

Term Description
Report An Advice report could also be referred to as a scenario. Each report has a Unique Identifier, cannot be modified and holds a snapshot of the input data and resulting calculations
Modules A report can be generated with optional modules turned on or off. The ability to use a particular module depends on the user’s active licence. more
Partners Openmarkets’ Software partners. To interact with the Advice API, you’ll need to register for a partner key. more
{base} Throughout this document, all endpoints begin with {base}. The value for this should have been provided to you when you registered for a Partner Key. All development and testing must be done against the sandbox environment. Only your production environment should be using the Advice production base url (and related partner key).

Advice Concepts

Firstly, let’s run through what Advice does and how your calls to the API will function.

Advice works on the principle of sending a set of input data, running the calculations, generating a ‘report’ and finally getting back the results. This calculation is incredibly complex and can take up to a minute depending on configuration and which modules are enabled.

Before we talk about Authentication, let’s have a look at how you’ll use Advice to generate results (called ‘running a report’)

Running Advice

The main resource you will be using is the reports endpoint
POST {base}/reports responds with:

{
  "success": true,
  "id": "reportId"
}

Keep Polling GET {base}/reports/{id}/status until you get:

"complete"

Then GET {base}/reports/{id} for the JSON representation or GET {base}/reports/{id}/url to get the link to the report in the front-end app.

Once a ‘report’ is generated it is given an ID and made permanently available to GET the results. There is no way to update or alter this report. If you want to make adjustments and check the results of that, then simply generate a new report.
You’ll soon see that you can generate a new report based on an existing one

Process:

  1. Generate a report with POST {base}/reports
  2. Get the report ID from the response id
  3. Check for completion by polling GET {base}/reports/{id}/status
  4. Once you get a response of “complete”, do either
    a. GET {base}/reports/{id} for a JSON representation or
    b. GET {base}/reports/{id}/url for the link to the report in the frontend app

Generate Report Flow

Modules

To Turn on and off modules when generating a report, include the following in your POST body:

{
  "core": {
    ...,
    "modules": {
      {
        "id": "optimisation",
        "run": true
      },
      {
        "id": "insurance",
        "run": true
      }
    }
  }
}

A single run of Advice can include different modules. The ones currently available are:

Which ones can be used depend upon the licence type held by the authenticated user. Presuming all are available to the current user, they can be turned on or off for a particular report run by adding an object to core.modules in the POST body.

Note: Each user can have different default settings against their account. These are setup at the time of account creation and (as long as the module is available to the user) can be overridden at runtime. See (#Configuration)

Configuration

Each authenticated user has a configuration setup when the account was created. This determines how Advice behaves, including:

This is important to understand since Advice will behave differently depending on who is the Authenticated user at the time.

Authentication

Users

An end user (such as a financial advisor) is the one with the licence to use Advice. You cannot make a call to the Advice API without a user account. Partner Keys are something different (See Partners)

As a developer, you should have received a developer user account with your Partner registration.

Partners

Remember to use your partnerKey and partnerSecret when authenticating with the API

Any software making a request to the Advice API must have a partner key and secret. These aren’t your login credentials but they help us ensure proper use of our API. To authenticate you will also need user credentials.

Authentication Procedure

Use one of the provided Authentication methods described below to obtain an access token. Once you have an Access token, simply add it as an ‘Authorization Header’ prefixed by ‘Bearer ‘.

"Authorization": "Bearer {accessToken}"

Depending on your use case, we have provided different ways of gaining an access token. (See [Authentication Methods](#Authentication Methods) for more details).

Once you have your access token, you will be able to use it to make further API calls. Just include it in the header as a ‘Bearer Token’.

The expiry of your access token can be tested using the expires attribute. Once this time has passed hit
POST {base}/oauth/token with the following to obtain a new token.

{
  "grant_type": "refresh_token",
  "client_id": "your provided partner key",
  "refresh_token": "refreshToken from previous calls"
}

Refreshing the Access Token
An Accees token is valid for 1 hour. You can check validity against the expires attribute in the response. Once this has expired you can use the refresh endpoint to get a new access token.

Authentication Methods

You can authenticate access to the API using one of two different methods: (please consult with the Advice team if you are unsure of the method for your situation)

oAuth Client Login

oAuth Method
Direct user to:

{base}/oauth/authorize?response_type=code&client_id={partner_id}&redirect_uri={redirect_uri}&scope=generate

POST {base}/oauth/token

{
  "grant_type": "authorization_code",
  "code": "{authorization_code from previous step}",
  "client_id": "{partner_id}",
  "redirect_uri": "{redirect_uri}"
}

Successful authentication will get a response of:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3599,
  "refresh_token": "...",
  "scope": "generate"
}
  1. Frontend Application is iFraming the Advice Application
  2. Your App (Front or Backend) is accessing Advice on behalf of a user

Using oAuth is a 3 step process, removing the need for you to handle any user credentials for Advice

  1. Direct user to the Advice Login page:
    Include the following parameters in the URL
  1. Upon successful login, user will be redirected to {redirect_uri} with a single use Authorization Code (code) and state if provided

  2. POST the Authorization Code (code) to the Advice API to exchange for an access_token. You can now use this token to access the API as per usual. (See Authentication Procedure for more details).

Direct Login with user credentials

Direct Login Method: POST {base}/oauth/token with:

{
  "grant_type": "password",
  "username": "email address",
  "password": "password",
  "client_id": "provided partnerKey",
  "redirect_uri": "The Redirect URI you provided when signing up for a partner key"
}

Successful authentication will get a response of:

{
  "accessToken": "...",
  "expires": "1521039256",
  "refreshToken": "...",
  "success": true
}

POST {base}/oauth/token with grant_type = password

You can then use the access token on future calls

Making Calls to the API

Headers

For calls to our API always include the following in the Header:

'Content-Type: application/json'
'Accept: application/json'

For most endpoints you’ll also need to include the following, once you’ve performed the Authentication procedure and retrieved a valid Access Code:

'Authorization: Bearer {accessCode}'

Every Call to the Advice API accepts the following header parameters:

Key Value Note
Authorization ‘Bearer {accessCode}’ only on secure endpoints
Content-Type ‘application/json’ required
Accept ‘application/json’

Endpoints

Greate a new Report

POST /reports

POST {base}/reports with the following to begin generation of a new report.

{
  "core": {
    "combined": {
      "home": {
        "isOwnHome": true,
        "valuation": 1000000
      }
    },
    "persons": [
      {
        "details": {
            "name": "Firstname",
            "age": 40
        },
        "work": {
            "status": "employed",
            "income": 100000
        },
        "super": {
          "totalAssets": 70000,
          "assetAllocationCategory": "balanced"
        }
      }
    ]
  }
}

Which, if there are no validation errors, will result in a response like so:

{
    "success": true,
    "id": "{reportId}"
}

The process of generating a report is explained in more detail above under - Running Advice

The POST body on the right is a minimal example to keep this brief. For a full set of attributes, refer to the Report Data Attributes list

Once you have received a response, you will need to poll for the report generation status (this can take up to a minute)

Get the report status

GET {base}/reports/{reportId}/status with the report Id you received previously.

{
    "status": "pending"
}

Keep checking every 5 seconds or so until you receive {"status":"complete"}

Get a report

Once the generation is complete, you can choose to either:

  1. get the raw report data for use in your application, or
  2. open the report in the Advice application (either as a new tab or as an iFrame)
  3. get the report as a PDF download

1. Get Report Data

GET {base}/reports/{reportId} with the report Id you received previously. You will receive back the results of the report you generated with the following objects:

{
    "output": {
        "core": "Basic information about the report itself",
        "meta": "Any additional metadata attached to the report",
        "retirement": "The results of the retirement income optimisation module",
        "insuranceNeeds": "The results of the insurance Needs module"
    },
    "input": "A copy of the data you sent to generate the report (including any defaults that have been added",
    "success": true
}

You’ll get a full representation of the report data, including the input that was provided to generate the report, in JSON format.

2. Get a url to view the data

GET {base}/reports/{reportId}/url to get the url to view this report in the browser

{
    "url": "https://app.investfit.io/reports/##uuid##",
    "success": true
}

Once you have the url to view the report, you can open it in a new tab, or iFramed inside your application

3. Download a PDF of the report

GET {base}/reports/{reportId}/pdf

The browser will stream a download of the file for saving locally

Errors

The Advice API uses the following error codes:

Error Code Meaning
400 Bad Request – There was a problem with the way your request was formatted
401 Unauthorized – Your access Token is incorrect
403 Forbidden – You are correctly authenticated, but don’t have access to this resource
404 Not Found – The specified endpoint could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.