This guide is for users of our Investor Compass 2.0 API. If you are unsure of what version of Investor Compass you are currently using, please visit this guide.
Contents
How to post the agreed risk level
An agreed risk level should be posted to the API if the adviser has had a conversation with the client and agreed on the risk level that they will take with their investments. This may be different to the suitable risk level calculated by Investor Compass. Once an agreed risk level has been posted, it will appear on PDF’s.
To post it, a question reference of SELECTED_RISK_PROFILE needs to be appended to the most recent instrument response for the client with any of the following answer_value_refs:
| Answer_value_ref | Risk Level |
| SELECTED_RISK_PROFILE_1 | Very Low |
| SELECTED_RISK_PROFILE_2 | Low |
| SELECTED_RISK_PROFILE_3 | Medium Low |
| SELECTED_RISK_PROFILE_4 | Medium |
| SELECTED_RISK_PROFILE_5 | Medium High |
| SELECTED_RISK_PROFILE_6 | High |
| SELECTED_RISK_PROFILE_7 | Very High |
You will need to get the most recent instrument response ID which can be done by making a GET request to the instrument responses endpoint
The question can be appended making a PUT request to the relevant instrument response ID. Documentation and samples can be found here: https://docs.oxfordrisk.io/docs/#tag/Response-Operations/operation/updateInstrumentResponse
How to update financials
Investible Accounts
Adding new investible accounts
You can add to accounts by setting the status of the existing account group to ARCHIVED with a PUT request and then creating a new account group containing all of the current accounts.
Changing the value of an existing account
You can change the value of an existing account by setting the status of the existing account group to ARCHIVED with a PUT request and then creating a new account group containing all of the current accounts and their current values.
Removing an account
This would be applicable if the value of an account is now 0, or if an investor has closed an account. You can remove an account by setting the status of the existing account group to ARCHIVED with a PUT request and then creating a new account group containing all the remaining accounts. If the client has no accounts, there is no need to create a new account group, but note that Investor Compass will not calculate a risk capacity result without an investible account.
Cashflows
Adding new cashflows
You can add a new cashflow by sending a POST request to the cashflow endpoint. Ensure that the new cashflow has a unique reference.
Updating the value or date of an existing cash flow
Send a POST request to the cashFlows endpoint with the corrected information. Ensure that you are using the same reference as the existing item. This will update the existing item.
Please note that when updating a cash flow, the previous cash flow will be archived and a new cash flow with the new details will then be created. This process is usually instantaneous, but there may be a short delay before the new cash flow is visible.
Removing a cash flow
The correct posting depends on the scenario:
If you are correcting a mistake (the cash flow should never have been there), you can delete it using the DELETE request to the cashFlows endpoint. Please note that deleted cash flows cannot be recovered.
If the client’s circumstances have changed (e.g. they are no longer receiving an income), you can mark the cashflow as inactive by cashflow by sending a POST request to the cashFlows endpoint with the same reference and setting the ‘active_end’ date to yesterday’s date. This will mean that it will no longer be considered in future, but if you run a risk profile report as at a historic date, it will be included.
What is the difference between the start, end, active_start and active_end fields for cashflows?
The active_start and active_end fields are automatically created by the API and represent the dates between which the algorithm will consider a cash flow when calculating risk capacity. For example, a cashflow with an active_start date of 2024-01-01 and an active_end date of 2025-01-01 will be taken into account for risk profiles run between these dates (or risk profiles set to run for a particular date in this range).
Any cashflows without an active_end date are currently being taken into account by the algorithm.
The start and end dates can be set through the API, telling Investor Compass when incomes and expenditures start and end. A cash flow without an end date is assumed to continue indefinitely.
Cash flows can be returned using the Get cashFlows endpoint. If the active_end query parameter is used, the API will return cashflows that were being considered by the algorithm on this date. It may not align with the actual start and end dates of the cash flows.
Non-Investible Assets and Liabilities
Adding new non-investible assets and liabilities
You can add a new cashflow by sending a POST request to the nonInvestibles endpoint. Ensure that the new nonInvestible has a unique reference.
Updating the value of an existing non investible/liability
Send a POST request with the corrected information to the nonInvestibles endpoint with the same reference as the existing item. This will update the existing item.
Please note that when updating a non investible, the previous non investible will be archived and a new non investible with the new details will then be created. This process is usually instantaneous, but there may be a short delay before the new non investible is visible.
Removing a non-investible/liability
The correct posting depends on the scenario:
If the previously entered item was incorrect, you can delete it by making a DELETE request to the nonInvestibles endpoint. Please note that deleted non investibles cannot be recovered.
If the client’s situation has changed (e.g. they have sold a property), you can mark the item as inactive by sending a POST request to the nonInvestibles endpoint with the same reference and setting the ‘active_end’ date to yesterday’s date. This will mean that it will no longer be considered in future, but if you run a risk profile report as at a historic date, it will be included.
How to produce a PDF
To produce a PDF, you must first create a snapshot. This will rebuild the PDF with the latest data and results available for the client. This may take a few seconds. You can check on the progress of the snapshot generation by making a GET request to the aSyncTask endpoint.
Once the snapshot has been created, you can then make a GET request to the report endpoint, which will return the BASE64 encoded PDF string.
Producing a historic PDF
PDF’s can be produced from historical snapshots that have been generated. You can see a list of these by posting a GET request to the snapshots endpoint. The snapshot ID returned can then be supplied as a parameter to the report endpoint to return the PDF as at the date of the snapshot.
Creating an approved PDF
Creating an approved PDF updates the status on the 2nd page of the report to show as Approved. This is normally once an adviser has spoken to the client and agreed a risk level to take with their assets. To create an approved PDF, complete the following steps:
Set an agreed risk level
(see the 'How to post the agreed risk level' section above)
Set the most Instrument Response status to approved.
You will need to GET all instrument responses and then post a PUT request to the most recent one, setting the status to APPROVED.
Create a snapshot
The snapshot you create needs to have {"status": "approved"} and {"approved_date": "YYYY-MM-DD"} in the payload.
Get the Report PDF
You can then call the GET on the report endpoint, which will return the BASE64 encoded PDF string.
Comments
0 comments
Please sign in to leave a comment.