API Documentation


Overview

Version information

Version 1.0.0

Contact information

Contact: EValue Support - support@ev.uk

URI scheme

Schemes: HTTP, HTTPS

Consumes

application/json

Produces

application/json

Paths

/forecastInvestment/forecast

Description

Investment Planner shows the benefits of investing based on a specific set of funds and/or asset classes. The Investment Forecast API generates a simple stochastic forecast based on an initial sum, regular contributions to, or withdrawals from, the investment, any initial, tiered and ongoing annual charges, taxation basis, term of investment and the funds or assets that the money is invested in. The API also requires the call to specify whether the results should be in today's or future values and which percentiles are required in the response, i.e. there is a 50% chance of the investment fund being less than x after the given term. Further detail on each of the above areas can be found in the Definitions section below. Please refer to the Pricing Plan and the Credits Plan for the number of credits required to call this API.

Parameters

Type Name Description Schema Required
BodyParameter body Parameters for investment forecast InvestmentForecastParameters true

Responses

HTTP Code Description Schema
200 successful operation ForecastResult
400 Validation errors ValidationErrors
500 System error SystemError

Definitions

Request

Please note that only the following Definitions will be used when calculating the Result of this API call. Any other data submitted will not be validated or used in the calculation.

InvestmentForecastParameters

Name Description Schema Required Range
contributions The regular contributions to be added to the investment Contributions  
withdrawals Regular withdrawals to be made from the investment Withdrawals  
initialCharges The charges to be applied to the initial investment amounts InitialCharges  
annualCharges The charges to be applied to the fund on an ongoing basis AnnualCharges  
accumulationTaxationBasis Choice of taxation basis for investment: either no tax adjustment or apply a 0.5% deduction to allow for taxation, in line with FCA rules Enum - NONE, FCA_TAXED true  
funds The funds that will be used in the investment projections List of Fund true  
forecastOptions The options available for the investment projections ForecastOptions true  

Contributions

Name Description Schema Required Range
amount Regular contribution to be included in the forecast Double true  
frequency Frequency of regular monetary amount contributions Enum - WEEKLY, MONTHLY, QUARTERLY, ANNUALLY true  
increase Increase to apply to pound-amount regular contributions (Increase applied annually). If an increase is required for percentage contributions then please use the salary increase Increase  

Increase

Name Description Schema Required Range
basis The underlying index to base the increase on. This can be one of NONE, RPI, CPI or AWE (average weekly earnings) Enum - NONE, RPI, CPI, AWE  
rate An additional rate of increase to apply each year on top of the increase basis. For a fixed increase rate basis should be set to NONE and rate to the fixed increase (i.e. basis = NONE, rate = 2.5 would use fixed 2.5% increases each year) Double -100 to 100

Withdrawals

Name Description Schema Required Range
percentage A boolean entry to determine if the withdrawals made from the investment should be a pound amount (false) or a percentage of the fund (true) Boolean true  
amount The amount to withdraw from the fund on an annual basis. If percentage has been specified, then the amount should release to the annual percentage required e.g. 2.5 for 2.5% per annum Double true  
increase Increase to apply to regular withdrawals. (Increase applied annually.) Increase  
startDate The date you would like the withdrawal from assets to start String (date)  

InitialCharges

Name Description Schema Required Range
percentage Initial charge applied to the starting balance (as % of balance) Double 0 to 100
amount Initial charge applied to the starting balance (in pound amount terms) Double 0 to 99,999
contributionPercentage Initial charge applied to any future contributions upon deposit (as % of contribution) Double 0 to 100

AnnualCharges

Name Description Schema Required Range
amount Annual pound amount charge. Double 0 to 99,999
tieredCharges Charges to apply at different tiers. Please provide these tiers in order from smallest to largest upperLimit. List of TieredCharge  

TieredCharge

Name Description Schema Required Range
percentage Annual % pa charge to apply to product (excluding fund charge) Double 0 to 100
upperLimit Balance up to which to apply the annual % charge specificied. If excluded, assume charge applies to whole balance Double 0 to 999,999,999

Fund

Name Description Schema Required Range
code Enter fund code for forecast. Use Citicode or asset class - see documentation for further information on asset class codes. String true  
riskGroup User's risk benchmark to which their investment can be evaluated Integer  
riskTerm Evaluated term for the efficient risk profile. Required if riskGroup is set. Integer 0 to 75
balance Balance in this fund Double true -999,999,999 to 999,999,999
contributionPercentage Contribution percentage allocated to that fund. Double true -100 to 200
adjustment Fund charge to apply to this fund. Enter charges as positive value, e.g. 1.5 for a 1.5% pa fund charge. Double -99 to 99
portfolioFunds A portfolio of funds. List of PortfolioFund  

PortfolioFund

Name Description Schema Required Range
code Enter fund code for forecast. Use Citicode or asset class - see documentation for further information on asset class codes. String true  
contributionPercentage Contribution percentage allocated to that fund. Double true -100 to 200

ForecastOptions

Name Description Schema Required Range
terms Terms for which to return a result, between 0 and 75 years List of Integer true  
todaysPrices True will return real results in today's values (i.e. values that have been adjusted to allow for inflation), and false will return nominal results in future values Boolean true  
todaysPricesIndex Index to use for discounting purposes if today's prices has been selected (i.e. the inflation measure used to roll back asset values in order to display 'real' results). This could be RPI or CPI and does not affect any of the increases specified elsewhere. If not included, a default of RPI will be used Enum - NONE, RPI, CPI, AWE  
percentiles Percentiles for which to return a result. The lowest result would be 0; the highest 100 List of Integer true  

Response

ForecastResult

Name Description Schema
results A list of results for each percentile requested in the API input parameters. List of PercentileResult

PercentileResult

Name Description Schema
percentile The percentile the results relate to Integer
terms A list of results for each term requested in the API input parameters List of TermResult

TermResult

Name Description Schema
value The relevant term's total value held; the tax basis for this will be dependant upon the API input Double
term The term of this forecast result Integer

ValidationErrors

Name Description Schema
errors A list of errors from validating the API input parameters List of ValidationError

ValidationError

Name Description Schema
field The field that is invalid String
code The type of validation error that has occurred Enum - REQUIRED, OUT_OF_RANGE, INVALID, INVALID_TOTAL
message The validation error message String
value The value that is invalid String

SystemError

Name Description Schema
systemError The system error message. String

Asset Classes

Where fund codes are required as input, you can instead refer to asset classes. See list of codes you can use for assets below.

Code Description
Returns_File_Cash Cash
Returns_File_Government_Bonds UK Government Bonds
Returns_File_Index_Linked_Bonds UK Index Linked Bonds
Returns_File_Corporate_Bonds_Inv_Grade Corporate Bonds - Investment Grade
Returns_File_Corporate_Bonds_High_Yield Global High Yield Bonds
Returns_File_Global_government_bonds Global Bonds
Returns_File_UK_Equity UK Equity
Returns_File_US_Equity US Equity
Returns_File_Europe_Equity European Equity
Returns_File_Japan_Equity Japanese Equity
Returns_File_Asia_ex_Japan_Equity Asia ex Japan Equity
Returns_File_Global_Emerging_Market_Equity Emerging Markets Equity
Returns_File_Small_cap_UK UK Small Cap Equity
Returns_File_Property UK Property
Returns_File_International_property International Property
Returns_File_Alpha_Strategies Alternative Investments
Returns_File_Commodities Commodities
Returns_File_Inflation Price Inflation
Returns_File_Nil_return Nil return