{"swagger":"2.0","info":{"description":"Uses EValue's calculation engine and Insight asset model to calculate the level of target retirement income at which an employee can meet 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.","version":"1.0.0","title":"DrawdownBacksolveIncome","contact":{"name":"EValue Support","url":"https://www.ev.uk","email":"support@ev.uk"}},"schemes":["https","http"],"consumes":["application/json"],"produces":["application/json"],"paths":{"/drawdownBacksolveIncome/forecast":{"post":{"summary":"","description":"","operationId":"forecast","produces":["application/json"],"parameters":[{"in":"body","name":"body","description":"Parameters for Drawdown Backsolve Income","required":true,"schema":{"$ref":"#/definitions/DrawdownBacksolveIncomeParameters"}}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/DrawdownBacksolveIncomeResult"}},"400":{"description":"Validation errors","schema":{"$ref":"#/definitions/ValidationErrors"}},"500":{"description":"System error","schema":{"$ref":"#/definitions/SystemError"}}}}}},"definitions":{"DrawdownBacksolveIncomeParameters":{"type":"object","required":["assets","backsolveOptions","forecastOptions","targetOptions","user"],"properties":{"user":{"description":"Information about the user","$ref":"#/definitions/User"},"assets":{"type":"array","description":"Information about the assets being forecasted","items":{"$ref":"#/definitions/Asset"}},"definedBenefits":{"type":"array","description":"Information about the defined benefit pensions, if any","items":{"$ref":"#/definitions/DefinedBenefit"}},"targetOptions":{"description":"Information about the income being targeted","$ref":"#/definitions/TargetOptions"},"forecastOptions":{"description":"Options surrounding the forecasting of results","$ref":"#/definitions/ForecastOptions"},"backsolveOptions":{"description":"Options to determine how the backsolve is calculated","$ref":"#/definitions/BacksolveOptions"}}},"Asset":{"type":"object","required":["funds","typeReference"],"properties":{"typeReference":{"type":"string","example":"PCPension","description":"The type of asset held, this could be in the form of an ISA, Personal Pension, Cash deposit or any other pension or investment."},"contributions":{"description":"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.","$ref":"#/definitions/Contributions"},"initialCharges":{"description":"Charges applied to the initial contributions and lump sums invested into the asset.","$ref":"#/definitions/InitialCharges"},"annualCharges":{"description":"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.","$ref":"#/definitions/AnnualCharges"},"funds":{"type":"array","example":[{"code":"KEBA","balance":100000,"contributionPercentage":80,"adjustment":0.1},{"code":"G6HZ","balance":25000,"contributionPercentage":20,"adjustment":0.25}],"description":"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.","items":{"$ref":"#/definitions/Fund"}}},"description":"An item owned by a person, regarded as having value and available to meet debts, commitments, or legacies."},"AnnualCharges":{"type":"object","properties":{"amount":{"type":"number","format":"double","example":0,"description":"Annual pound amount charge.","minimum":0,"maximum":99999},"tieredCharges":{"type":"array","example":[{"percentage":0.45,"upperLimit":50000},{"percentage":0.25}],"description":"Charges to apply at different tiers. Please provide these tiers in order from smallest to largest upperLimit.","items":{"$ref":"#/definitions/TieredCharge"}}},"description":"Annual Charges object for adding an annual charge as well as tiered platform charges"},"TieredCharge":{"type":"object","properties":{"percentage":{"type":"number","format":"double","example":0.45,"description":"Annual % pa charge to apply to product (excluding fund charge)","minimum":0,"maximum":100},"upperLimit":{"type":"number","format":"double","example":50000,"description":"Balance up to which to apply the annual % charge specificied. If excluded, assume charge applies to whole balance","minimum":0,"maximum":999999999}},"description":"Allows for tiered platform charges"},"Contributions":{"type":"object","required":["amount","frequency","percentage","taxBasis"],"properties":{"amount":{"type":"number","format":"double","example":500,"description":"Regular contribution to be included in the forecast"},"frequency":{"type":"string","example":"MONTHLY","description":"Frequency of regular monetary amount contributions","enum":["WEEKLY","MONTHLY","QUARTERLY","ANNUALLY"]},"increase":{"description":"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","$ref":"#/definitions/Increase"},"taxBasis":{"type":"string","description":"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"]},"percentage":{"type":"boolean","example":false,"description":"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"},"stopDate":{"type":"string","format":"date","example":"2030-01-01","description":"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"},"employerAmount":{"type":"number","format":"double","example":0,"description":"The contributions paid into the employee's investment by the employer"}},"description":"Regular contributions to be forecast"},"Increase":{"type":"object","properties":{"basis":{"type":"string","example":"RPI","description":"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":{"type":"number","format":"double","example":0,"description":"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)","minimum":-100,"maximum":100}},"description":"An Increase to apply"},"Fund":{"type":"object","required":["balance","code","contributionPercentage"],"properties":{"code":{"type":"string","example":"Returns_File_UK_Equity","description":"Enter fund code for forecast. Use Citicode or asset class - see documentation for further information on asset class codes."},"riskGroup":{"type":"integer","format":"int32","description":"User's risk benchmark to which their investment can be evaluated"},"riskTerm":{"type":"integer","format":"int32","description":"Evaluated term for the efficient risk profile. Required if riskGroup is set.","minimum":0,"maximum":75},"balance":{"type":"number","format":"double","description":"Balance in this fund","minimum":-999999999,"maximum":999999999},"contributionPercentage":{"type":"number","format":"double","example":100,"description":"Contribution percentage allocated to that fund.","minimum":-100,"maximum":200},"adjustment":{"type":"number","format":"double","example":0.25,"description":"Fund charge to apply to this fund. Enter charges as positive value, e.g. 1.5 for a 1.5% pa fund charge.","minimum":-99,"maximum":99},"portfolioFunds":{"type":"array","description":"A portfolio of funds.","items":{"$ref":"#/definitions/PortfolioFund"}}},"description":"A fund an investment can be invested in."},"PortfolioFund":{"type":"object","required":["code","contributionPercentage"],"properties":{"code":{"type":"string","example":"Returns_File_UK_Equity","description":"Enter fund code for forecast. Use Citicode or asset class - see documentation for further information on asset class codes."},"contributionPercentage":{"type":"number","format":"double","example":100,"description":"Contribution percentage allocated to that fund.","minimum":-100,"maximum":200}},"description":"A fund an investment can be invested in."},"InitialCharges":{"type":"object","properties":{"percentage":{"type":"number","format":"double","example":0,"description":"Initial charge applied to the starting balance (as % of balance)","minimum":0,"maximum":100},"amount":{"type":"number","format":"double","example":0,"description":"Initial charge applied to the starting balance (in pound amount terms)","minimum":0,"maximum":99999},"contributionPercentage":{"type":"number","format":"double","example":0,"description":"Initial charge applied to any future contributions upon deposit (as % of contribution)","minimum":0,"maximum":100}},"description":"Intial charges for the investment"},"BacksolveOptions":{"type":"object","required":["dateMoneyRunsOut","probability"],"properties":{"dateMoneyRunsOut":{"type":"string","format":"date","example":"2051-01-01","description":"The date that you want your money to last until."},"probability":{"type":"integer","format":"int32","example":50,"description":"The probability that you will meet the target specified, at the term requested.","minimum":0,"maximum":100}},"description":"Options to determine how the backsolve is calculated"},"DefinedBenefit":{"type":"object","required":["income","startDate","todaysPrices"],"properties":{"income":{"type":"number","format":"double","example":10000,"description":"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.","minimum":0,"maximum":999999999},"todaysPrices":{"type":"boolean","example":true,"description":"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"},"startDate":{"type":"string","format":"date","example":"2031-01-01","description":"ISO-8601 formatted date at which the defined benefit payments commence"},"incomeIncrease":{"description":"Increase rate to apply to the defined benefit payments. If not included, then no increase will be applied.","$ref":"#/definitions/Increase"}},"description":"A pension that will be paid for life from retirement"},"ForecastOptions":{"type":"object","required":["retirementDate","taxOptions","todaysPrices"],"properties":{"todaysPrices":{"type":"boolean","example":true,"description":"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"},"todaysPricesIndex":{"type":"string","example":"CPI","description":"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"]},"retirementDate":{"type":"string","format":"date","example":"2030-01-01","description":"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"},"taxBasis":{"type":"string","example":"NET","description":"To determine if the results should be presented Net or Gross of tax. This must match the taxBasis set under TargetOptions. Defaults to NET.","enum":["GROSS","NET"]},"taxOptions":{"description":"The Tax Options for the forecast","$ref":"#/definitions/TaxOptions"},"lumpSumPercentage":{"type":"number","format":"double","example":25,"description":"Decimal percentage of the fund value to take as a cash lump sum","minimum":0,"maximum":100},"partialAnnuityPercentage":{"type":"number","format":"double","example":10,"description":"Decimal percentage of the Partial annuity","minimum":0,"maximum":100}},"description":"Options dictating how the forecast should be processed"},"TaxOptions":{"type":"object","required":["region"],"properties":{"region":{"type":"string","example":"UK","description":"In addition to the tax jurisdiction, further specifies tax assumptions","enum":["UK","SCOTLAND"]}},"description":"Specifies the region for the tax"},"TargetOptions":{"type":"object","properties":{"target":{"type":"number","format":"double","example":15000,"description":"Decimal value of the target","readOnly":true,"minimum":0,"maximum":999999999},"increase":{"description":"The increase rate to apply to the target income. If not included, a default of RPI will be used","$ref":"#/definitions/Increase"},"taxBasis":{"type":"string","description":"The tax basis of the specified target amount. This must match the taxBasis set under ForecastOptions.","enum":["GROSS","NET"]}},"description":"Options relating to the target income the user wants in retirement"},"User":{"type":"object","required":["dateOfBirth","gender","salary","salaryIncrease"],"properties":{"dateOfBirth":{"type":"string","format":"date","example":"1965-01-01","description":"ISO-8601 formatted date of birth for the forcastee"},"gender":{"type":"string","example":"MALE","description":"Gender of the forcastee","enum":["MALE","FEMALE"]},"stateBenefit":{"description":"The details of the state pension to be calculated for this person","$ref":"#/definitions/StateBenefit"},"salary":{"type":"number","format":"double","example":50000,"description":"Decimal salary of the forcastee. Required if contributions are entered as a percentage of salary)","minimum":0,"maximum":999999999},"salaryIncrease":{"description":"The increase rate to apply to the forcastee's salary","$ref":"#/definitions/Increase"},"spouse":{"description":"Object containing information on the spouse of the forcastee","$ref":"#/definitions/Spouse"}},"description":"The main user, the 'forecastee'"},"Spouse":{"type":"object","required":["dateOfBirth","gender"],"properties":{"dateOfBirth":{"type":"string","format":"date","example":"1969-01-01","description":"ISO-8601 formatted date of birth of the forcastee's spouse"},"gender":{"type":"string","example":"FEMALE","description":"Gender of the forcastee's spouse","enum":["MALE","FEMALE"]},"stateBenefit":{"description":"The details of the state pension to be calculated for the spouse","$ref":"#/definitions/StateBenefit"}},"description":"The partner of the main user"},"StateBenefit":{"type":"object","properties":{"include":{"type":"boolean","example":true,"description":"Whether to include the state benefit in the forecast"},"amount":{"type":"number","format":"double","example":8325,"description":"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","minimum":0,"maximum":999999999}},"description":"Details of the state pension"},"DrawdownBacksolveIncomeResult":{"type":"object","properties":{"targetOptions":{"description":"Information about the backsolve income which is being targeted.","$ref":"#/definitions/TargetOptions"},"error":{"type":"string","description":"This field is returned when the system is unable to achieve a solution."}}},"ValidationErrors":{"type":"object","properties":{"errors":{"type":"array","description":"A list of errors from validating the API input parameters","items":{"$ref":"#/definitions/ValidationError"}}},"description":"Contains any errors that have occurred during validation of the API input parameters"},"ValidationError":{"type":"object","properties":{"field":{"type":"string","description":"The field that is invalid"},"code":{"type":"string","description":"The type of validation error that has occurred","enum":["REQUIRED","OUT_OF_RANGE","INVALID","INVALID_TOTAL"]},"message":{"type":"string","description":"The validation error message"},"value":{"type":"string","description":"The value that is invalid"}},"description":"Contains details of a error when validating an API input parameter"},"SystemError":{"type":"object","properties":{"systemError":{"type":"string","example":"A system error has occurred.","description":"The system error message."}},"description":"A System error message"}},"securityDefinitions":{"default":{"type":"oauth2","authorizationUrl":"https://api-gateway.prod.powered-by.ev.uk/authorize","flow":"implicit","scopes":{}}},"basePath":"/drawdownBacksolveIncome/1.0.0","host":"api-gateway.prod.powered-by.ev.uk"}