Overview
Version information
Version 0.0.1
Contact information
Contact: EValue Support - support@ev.uk
URI scheme
Schemes: HTTP, HTTPS
Consumes
application/json
Produces
application/json
Paths
/retirementAnnuity/forecast
Description
Uses EValue's calculation engine and Insight asset model to calculate annuity forecast, plus value at retirement and lump sum, where relevant. Multiple pensions and investments are allowed plus State pensions and DB pensions. A target income can also be set. 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 retirement annuity forecast |
AnnuityForecastParameters |
true |
Responses
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.
AnnuityForecastParameters
Name |
Description |
Schema |
Required |
Range |
user |
The main user, the 'forecastee' |
User |
true |
|
assets |
A list of assets owned by a person, regarded as having value and available to meet debts, commitments, or legacies |
List of Asset |
true |
|
definedBenefits |
A list of defined benefit pensions owned by a person |
List of DefinedBenefit |
true |
|
targetOptions |
Options relating to the target income the user wants in retirement |
TargetOptions |
|
|
forecastOptions |
Options dictating how the forecast should be processed |
ForecastOptions |
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 |
|
annuity |
The features of the annuity to be purchased during retirement. |
Annuity |
|
|
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 |
Annuity
Name |
Description |
Schema |
Required |
Range |
lumpSumPercentage |
Decimal value of the cash lump sum to take as a percentange. |
Double |
true |
0 to 100 |
pensionIncrease |
The increase rate to apply to the annuity income. The pensionIncrease basis can only be RPI or NONE. If not included, then no increase will be applied. |
Increase |
|
|
spousePercentage |
Integer value of the partner's percentage for this asset. If not included, then this will default to 0. |
Integer |
|
0 to 100 |
guaranteePeriod |
Integer value of the guarantee period in years. If not included, a default of 5 years will be used. |
Integer |
|
0 to 10 |
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 |
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 |
|
retirementDate |
ISO-8601 formatted date at which the forecastee should retire in the forecast. Please ensure that this date represents an age for the user that is 55 or older |
String (date) |
true |
|
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 |
true |
|
taxOptions |
The Tax Options for the forecast |
TaxOptions |
true |
|
deterministicOptions |
For use if deterministic projections should be used in annuity calculations rather than stochastic projections. |
DeterministicOptions |
|
|
TaxOptions
Name |
Description |
Schema |
Required |
Range |
region |
In addition to the tax jurisdiction, further specifies tax assumptions |
Enum - UK, SCOTLAND |
true |
|
DeterministicOptions
Name |
Description |
Schema |
Required |
Range |
assumption |
The deterministic assumptions to use in annuity calculations, one of LOW, CENTRAL or HIGH |
Enum - LOW, CENTRAL, HIGH |
|
|
Response
ForecastResult
Name |
Description |
Schema |
results |
A list of results for each percentile requested in the API input parameters. |
List of PercentileResult |
chanceOfBeatingTargetResults |
A list of results showing the percentage chance of beating the specified target at the specified term. |
List of ChanceTermResult |
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 |
income |
The relevant term's total income value after any specified tax |
Double |
lumpSum |
The relevant term's total lump sum value withdrawn from pensions |
Double |
term |
The term of this forecast result |
Integer |
ChanceTermResult
Name |
Description |
Schema |
term |
The term of this forecast result |
Integer |
chance |
The percentage chance of beating the relevant term's target |
Double |
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 |