post https://api-lib.bambu.life/api/returnsCalc/v2/projections
Based on the following inputs regarding user's:
- Financial Ability - Initial and Periodic Investment Amounts, and Number of Compounding Periods Per Year
- Goal Details - Goal Amount, Goal Start and End Date
- Investment Profile - Expected Returns and Volatilities of each Model Portfolio, Model Portfolio to be invested in each year, Confidence Level and Target Probability
- Fees - Front-end Fee, Back-end Fee and Management Fees
This API projects future expected portfolio values at each compound date based on expected annual returns and volatilities of Model Portfolios invested each year during the goal period. According to this, the API determines if investor's goal is achievable, and also returns probability of achieving goal. It also has the option to display various recommendations. Following describes some other specifics of the API:
- Compounding options - "yearly", "monthly", "weekly","quarterly","semiAnnually"
- Recommendations available:
- If goal is not achievable (SHORTFALL) - Change in Initial Investment Amount, Periodic Investment Amounts (Constant, Increasing and Decreasing), Goal Amount and Investment End Date
- If goal is achievable (SURPLUS) - A declining glide path that recommends investments in less risky Model Portfolios nearer to Goal End Date
The following table describes the input parameters for the Projections API:
| Name | DataType | Description | Mandatory | Sample Value | List of possible values | No. of Decimals | Notes |
|---|---|---|---|---|---|---|---|
| reccomendationSelection | Dictionary | Selection of recommendations to be displayed | Y | ||||
| shortfallRecommendation | Dictionary | Selection of recommendations to be displayed if there is a shortfall in investment to achieve goal | Y | ||||
| initialInvestment | Boolean | To display recommendation for initial investment amount | Y | true | true, false | N/A | |
| constantInfusion | Boolean | To display recommendation for constant infusion amount | Y | true | true, false | N/A | |
| dynamicIncreasingInfusion | Boolean | To display recommendation for increasing infusion amounts | Y | true | true, false | N/A | |
| dynamicDecreasingInfusion | Boolean | To display recommendation for decreasing infusion amounts | Y | true | true, false | N/A | |
| goalAmount | Boolean | To display goal amount achievable by end of investment | Y | true | true, false | N/A | |
| goalYear | Boolean | To display recommendation for investment end date | Y | true | true, false | N/A | |
| surplusRecommendation | Dictionary | Selection of recommendations to be displayed if there is a surplus in investment to achieve goal | Y | ||||
| glidePath | Dictionary | Settings for declining glide path recommendation | Y | true | true, false | N/A | |
| glidePath | Boolean | To display recommendation for declining glide path | Y | true | true, false | N/A | |
| portfolioDerisking | Boolean | To apply start and end dates for which glide path should happen | Y | true | true, false | N/A | |
| deriskingStartDate | String | Glide path start date | Y | "2015-01-02" | N/A | format: "%Y-%m-%d" | |
| deriskingEndDate | String | Glide path end date | Y | "2019-01-03" | N/A | format: "%Y-%m-%d" | |
| availablePortfolios | Array | Details of all Model Portfolios suitable for the client | Y | ||||
| modelPortfolioId | Integer | ID of the Model Portfolio | Y | 4 | >0 | 0 | |
| discreteExpectedMean | Number | Discrete mean of the Model Portfolio's annual returns | Y | 0.03 | >=0 , <1 | 6 | |
| discreteExpectedStandardDeviation | Number | Discrete standard deviation of the Model Portfolio's annual returns | Y | 0.05 | >=0, <1 | 6 | |
| inputs | Dictionary | Y | |||||
| startDate | String | Goal start date | Y | "2010-01-21" | N/A | format: "%Y-%m-%d" | |
| endDate | String | Goal end date | Y | "2012-03-30" | N/A | format: "%Y-%m-%d". endDate must be greater than startDate | |
| compounding | String | Compounding frequency | Y | "monthly" | "yearly", "semiAnnually", "quarterly", "monthly", "weekly" | N/A | |
| confidenceInterval | Number | Confidence level for computation of upper and lower band returns | Y | 0.9 | >=0, <=1 | 2 | |
| grossInitialInvestment | Number | Gross initial investment amount (before front-end fee) | Y | 298323 | >=0 | 2 | |
| currentWealth | Number | Current portfolio total value | Y | 11190 | >=0 | 2 | |
| frontEndFees | Number | Front-end fees in % | Y | 0.04 | >=0, <1 | 6 | |
| backEndFees | Number | Back-end fees in % | Y | 0.02 | >=0, <1 | 6 | |
| managementFees | List of numbers | Annual management fees levied on returns | Y | [0] | >=0, <1 | 6 | If no. of elements in this list < no. of years of investment tenure, the last element will be appended to the list until this condition is satisfied. If no. of elements in this list > no. of years of investment tenure, the extra elements will be ignored |
| grossGoalAmount | Number | Gross goal amount (before back-end fee) | Y | 228323 | >=0 | 2 | |
| modelPortfolioIdList | List of integers | IDs of Model Portfolios to be invested in each year. These IDs correspond the modelPortfolioId inputs in availablePortfolios section | Y | [13] | all modelPortfolioId defined in availablePortfolios | N/A | If no. of elements in this list < no. of years of investment tenure, the last element will be appended to the list until this condition is satisfied. If no. of elements in this list > no. of years of investment tenure, the extra elements will be ignored |
| infusions | List of numbers | Infusion amount on each compound date | Y | [100] | 2 | If no. of elements in this list < total times of compounding, the last element will be appended to the list until this condition is satisfied | |
| targetProbability | Number | Probability for computation of target returns | Y | 0.66 | >0 , <1 | 2 |
The following table describes the outputs from the Projections API:
| Name | DataType | Description | Sample Value | No. of Decimals | Notes |
|---|---|---|---|---|---|
| difference | Number | Difference between net goal amount (after back-end fee) and projected accumulated target portfolio value at the end of investment tenure | 10518 | 0 | Projected accumulated target portfolio value is computed with target returns |
| goalProbability | String | Probability of obtaining portfolio returns sufficient for achieving goal | 0.64041 | 6 | Round off to 6 dp |
| healthCheckPass | String | "SHORTFALL" - projected investment value is less than goal amount. "OK" - projected investment value is 0-5% above goal amount. "SURPLUS" - projected investment value is more then 5% above goal amount. | "SURPLUS" | N/A | |
| matchGoalProb | Boolean | "true" if goalProbability > targetProbability, "false" otherwise | false | N/A | |
| performanceTest | Dictionary | (if healthCheckStatus: SHORTFALL) | |||
| constantInfusionRecRunningTime | Number | Running time for constant infusion recommendation | 0.0175 | 4 | In seconds |
| dynamicDecreasingInfusionRecRunningTime | Number | Running time for decreasing infusions recommendation | 0.0549 | 4 | In seconds |
| dynamicIncreasingInfusionRecRunningTime | Number | Running time for increasing infusions recommendation | 0.0428 | 4 | In seconds |
| goalAmountRecRunningTime | Number | Running time for goal amount recommendation | 0.0 | 4 | In seconds |
| goalYearRecRunningTime | Number | Running time for goal year recommendation | 0.0017 | 4 | In seconds |
| initialInvestmentRecRunningTime | Number | Running time for initial investment recommendation | 0.0014 | 4 | In seconds |
| projections | Array | ||||
| date | String | Compound date | "2010-02-01" | N/A | Repeated for each compound date |
| goalAmountNet | Number | Net goal amount at each compound date | 232982.65 | 2 | Repeated for each compound date |
| projectionLowerAmt | Number | Projected accumulated lower band portfolio value at each compound date | 241572.65 | 2 | Repeated for each compound date |
| projectionMiddleAmt | Number | Projected accumulated middle band portfolio value at each compound date | 287840.63 | 2 | Repeated for each compound date |
| projectionTargetAmt | Number | Projected accumulated target portfolio value at each compound date | 275466.12 | 2 | Repeated for each compound date |
| projectionUpperAmt | Number | Projected accumulated upper band portfolio value at each compound date | 342970.24 | 2 | Repeated for each compound date |
| recommendations | Dictionary | (If healthCheckStatus: SHORTFALL) | |||
| constantInfusion | List of integers | The minimum constant infusion amount required to achieve goal | [447, 447, 447, ..., 447, 447, 447] | 0 | Round up to nearest whole number |
| dynamicDecreasingInfusion | List of integers | Infusion amounts in a decreasing manner required to achieve goal | [484, 483, 481, 479, 477, ..., 419, 412, 404, 396, 381] | 0 | Rounded up to nearest whole number |
| dynamicIncreasingInfusion | List of integers | Infusion amounts in an increasing manner required to achieve goal | [376, 391, 400, 407, 415, ..., 472, 475, 476, 478, 479] | 0 | Rounded up to nearest whole number |
| goalAmount | Number | Net goal amount achievable with current investment | 218014.64 | 2 | |
| initialInvestment | Integer | The minimum initial investment amount required to achieve goal | 312414 | 0 | Rounded up to nearest whole number |
| recommendations | Dictionary | (If healthCheckStatus: SURPLUS) | |||
| portfolioPath | Dictionary | Details of recommended glide path | |||
| discreteExpectedMean | List of numbers | Discrete mean of returns of selected Model Portfolio for each year | [0.12, 0.12, 0.12, 0.08, ..., 0.03] | 2 | |
| discreteExpectedStandardDeviation | List of numbers | Discrete standard deviations of returns of selected Model Portfolio for each year | [0.16, 0.16, 0.16, 0.1, ..., 0.05] | 2 | |
| modelPortfolioId | List of Integers | IDs of selected Model Portfolio for each year | [14, 14, 14, 13, ..., 4] | 0 | |
| runningTime | String | Total running time | "0.321 seconds" | N/A |