API Document


Overview

Version information

Version 0.1.0

Contact information

Contact: EValue Support - support@ev.uk

URI scheme

Schemes: HTTP, HTTPS

Consumes

application/json

Produces

application/json

Paths

/drawdownBacksolveRetirementAge/forecast

Description

Uses EValue's calculation engine and Insight asset model to calculate the retirement age at which an employee can meet a target retirement income until a set end age, when processing income drawdown. Multiple pensions and investments are allowed plus State pensions and DB pensions. 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 Drawdown Backsolve Retirement Age DrawdownBacksolveRetirementAgeParameters true

Responses

HTTP Code Description Schema
200 successful operation DrawdownBacksolveRetirementAgeResults
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.

DrawdownBacksolveRetirementAgeParameters

Name Description Schema Required Range
user Information about the user User true  
assets Information about the assets being forecasted List of Asset true  
definedBenefits Information about the defined benefit pensions, if any List of DefinedBenefit  
targetOptions Information about the income being targeted TargetOptions true  
forecastOptions Options surrounding the forecasting of results ForecastOptions true  
backsolveOptions Options to determine how the backsolve is calculated BacksolveOptions true  

User

Name Description Schema Required Range
dateOfBirth ISO-8601 formatted date of birth for the forcastee String (date) true  
gender Gender of the forcastee Enum - MALE, FEMALE true  
stateBenefit The details of the state pension to be calculated for this person StateBenefit  
salary Decimal salary of the forcastee. Required if contributions are entered as a percentage of salary) Double true 0 to 999,999,999
salaryIncrease The increase rate to apply to the forcastee's salary Increase true  
spouse Object containing information on the spouse of the forcastee Spouse  

StateBenefit

Name Description Schema Required Range
include Whether to include the state benefit in the forecast Boolean  
amount An optional state benefit amount to be used in the forecast. If not set, this value will default to the maximum current state pension amount Double 0 to 999,999,999

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

Spouse

Name Description Schema Required Range
dateOfBirth ISO-8601 formatted date of birth of the forcastee's spouse String (date) true  
gender Gender of the forcastee's spouse Enum - MALE, FEMALE true  
stateBenefit The details of the state pension to be calculated for the spouse StateBenefit  

Asset

Name Description Schema Required Range
typeReference The type of asset held, this could be in the form of an ISA, Personal Pension, Cash deposit or any other pension or investment. String true  
contributions Any additional money paid into your asset, either as a regular saving or as a one off payment. Could be paid by the employee or the employer or a combination of both. Contributions  
initialCharges Charges applied to the initial contributions and lump sums invested into the asset. InitialCharges  
annualCharges Charges in the form of a percentage, fixed or increasing monetary amount that are applied annually to the investment. Could also apply to the regular contributions. A percentage will be based on the fund value or added contributions. AnnualCharges  
funds The portfolio of investments that the asset held is based on. Could include a mixture of assets classes such as government bonds, cash, property or equities. List of Fund 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  
taxBasis The tax basis of the contributions. This is not utilised upon percentage contributions and the model will assume contributions are made direct from salary prior to taxation (ie GROSS). For NET contributions pound-amount, a 25% uplift will be applied Enum - GROSS, NET true  
percentage A boolean response to determine if the contributions entered are a percentage of salary (true) or a monetary amount (false) that may or may not increase over time Boolean true  
stopDate An optional date at which contributions will cease to be paid. If the date provided is after retirementDate then the contributions automatically cease at retirement String (date)  
employerAmount The contributions paid into the employee's investment by the employer Double  

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

DefinedBenefit

Name Description Schema Required Range
income The annual income payable from the defined benefit pension start date. If provided in future values this is the actual monetary income that will be achieved from the start date. Double true 0 to 999,999,999
todaysPrices Boolean indicating whether the income specified is in todays or future prices. If specified in todays prices then the income will increase with RPI until payment begins Boolean true  
startDate ISO-8601 formatted date at which the defined benefit payments commence String (date) true  
incomeIncrease Increase rate to apply to the defined benefit payments. If not included, then no increase will be applied. Increase  

TargetOptions

Name Description Schema Required Range
target Decimal value of the target Double true 0 to 999,999,999
increase The increase rate to apply to the target income. If not included, a default of RPI will be used Increase  
taxBasis The tax basis of the specified target amount. This must match the taxBasis set under ForecastOptions. Enum - GROSS, NET  

ForecastOptions

Name Description Schema Required Range
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  
taxBasis To determine if the results should be presented Net or Gross of tax. This must match the taxBasis set under TargetOptions Enum - GROSS, NET  
taxOptions The Tax Options for the forecast TaxOptions true  
lumpSumPercentage Decimal percentage of the fund value to take as a cash lump sum Double 0 to 100
partialAnnuityPercentage Decimal percentage of the Partial annuity Double 0 to 100

TaxOptions

Name Description Schema Required Range
region In addition to the tax jurisdiction, further specifies tax assumptions Enum - UK, SCOTLAND true  

BacksolveOptions

Name Description Schema Required Range
dateMoneyRunsOut The date that you want your money to last until. String (date) true  
probability The probability that you will meet the target specified, at the term requested. Integer true 0 to 100

Response

DrawdownBacksolveRetirementAgeResults

Name Description Schema
retirementDate The date you can retire to meet your target String (date)
retirementAge The age at the time of retirement 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