{"swagger":"2.0","info":{"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.","version":"1.0.0","title":"InvestmentForecast","contact":{"name":"EValue Support","url":"https://www.ev.uk","email":"support@ev.uk"}},"schemes":["https","http"],"consumes":["application/json"],"produces":["application/json"],"paths":{"/forecastInvestment/forecast":{"post":{"summary":"Simple investment forecast","description":"Notes for investment forecast","operationId":"forecast","produces":["application/json"],"parameters":[{"in":"body","name":"body","description":"Parameters for investment forecast","required":true,"schema":{"$ref":"#/definitions/InvestmentForecastParameters"}}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/ForecastResult"}},"400":{"description":"Validation errors","schema":{"$ref":"#/definitions/ValidationErrors"}},"500":{"description":"System error","schema":{"$ref":"#/definitions/SystemError"}}}}}},"definitions":{"InvestmentForecastParameters":{"type":"object","required":["accumulationTaxationBasis","forecastOptions","funds"],"properties":{"contributions":{"description":"The regular contributions to be added to the investment","$ref":"#/definitions/Contributions"},"withdrawals":{"description":"Regular withdrawals to be made from the investment","$ref":"#/definitions/Withdrawals"},"initialCharges":{"description":"The charges to be applied to the initial investment amounts","$ref":"#/definitions/InitialCharges"},"annualCharges":{"description":"The charges to be applied to the fund on an ongoing basis","$ref":"#/definitions/AnnualCharges"},"accumulationTaxationBasis":{"type":"string","example":"NONE","description":"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"]},"funds":{"type":"array","example":[{"code":"KEBA","balance":100000,"contributionPercentage":80},{"code":"G6HZ","balance":25000,"contributionPercentage":20}],"description":"The funds that will be used in the investment projections","items":{"$ref":"#/definitions/Fund"}},"forecastOptions":{"description":"The options available for the investment projections","$ref":"#/definitions/ForecastOptions"}},"description":"The parameters for an investment forecast"},"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"],"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"}},"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"},"ForecastOptions":{"type":"object","required":["percentiles","terms","todaysPrices"],"properties":{"terms":{"type":"array","example":[5,10,15],"description":"Terms for which to return a result, between 0 and 75 years","items":{"type":"integer","format":"int32"}},"todaysPrices":{"type":"boolean","example":false,"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"]},"percentiles":{"type":"array","example":[5,50,95],"description":"Percentiles for which to return a result. The lowest result would be 0; the highest 100","items":{"type":"integer","format":"int32"}}},"description":"Options dictating how the forecast should be processed"},"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"},"Withdrawals":{"type":"object","required":["amount","percentage"],"properties":{"percentage":{"type":"boolean","example":true,"description":"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)"},"amount":{"type":"number","format":"double","example":5,"description":"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"},"increase":{"description":"Increase to apply to regular withdrawals. (Increase applied annually.)","$ref":"#/definitions/Increase"},"startDate":{"type":"string","format":"date","example":"2021-01-01","description":"The date you would like the withdrawal from assets to start"}},"description":"Regular withdrawals to be forecast"},"ForecastResult":{"type":"object","properties":{"results":{"type":"array","example":[{"percentile":5,"terms":[{"value":140180.66,"term":5},{"value":191515.89,"term":10},{"value":243886.98,"term":15}]},{"percentile":50,"terms":[{"value":195982.88,"term":5},{"value":297411.28,"term":10},{"value":444908.03,"term":15}]},{"percentile":95,"terms":[{"value":276767.75,"term":5},{"value":496972.63,"term":10},{"value":894433.13,"term":15}]}],"description":"A list of results for each percentile requested in the API input parameters.","items":{"$ref":"#/definitions/PercentileResult"}}},"description":"The results of the forecast"},"PercentileResult":{"type":"object","properties":{"percentile":{"type":"integer","format":"int32","example":50,"description":"The percentile the results relate to"},"terms":{"type":"array","description":"A list of results for each term requested in the API input parameters","items":{"$ref":"#/definitions/TermResult"}}},"description":"Contains the results for a requested percentile"},"TermResult":{"type":"object","properties":{"value":{"type":"number","format":"double","description":"The relevant term's total value held; the tax basis for this will be dependant upon the API input"},"term":{"type":"integer","format":"int32","description":"The term of this forecast result"}},"description":"A forecast result for a particular term"},"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":"/inv-forecast/1.0.0","host":"api-gateway.prod.powered-by.ev.uk"}