post https://api-lib.bambu.life/api/generalCalculator/v2/goalCalculator/calcRetirementGoalAmount
Calculate the goal amount required for the whole retirement period such that user can retire comfortable with the estimated retirement amount
Request Data
| Name | Data Type | Technical Description | Mandatory | Sample Value | List of possible values | No. of decimals | Remarks |
|---|---|---|---|---|---|---|---|
| annualRetirementIncome | Number | Annual Retirement Income | Y | 95106.6 | >0 | 2 | The value comes from Retirement Monthly Expenditure Calculator API where annualRetirementIncome value is equivalent to 12*totalFutureDollarMonthlyExpenditure |
| retirementAge | Number | Retirement Age of user | Y | 65 | 0 | This comes from Country Service. If client wants their own value, then hardcode it in the Front End. Endpoint - country/v2/rates?countryCode=US field - retirementAgeMale | |
| gender | String | Gender of user | Y | Male | 'Male', 'Female' | Gender is either "Male" or "Female". if we are not asking for the user's gender, we assume he is a guy. Male | |
| lifeExpectancyMen | Number | Male Life Expectancy | Y | 81 | >RetirementAge | 2 | Male Life Expectancy can either be hardcoded as per client's request or can be obtained from the "Country rates APIs by the country code" field to use - lifeExpectancyMale |
| lifeExpectancyFemale | Number | Female Life Expectancy | Y | 86 | >RetirementAge | 2 | Female Life Expectancy can either be hardcoded as per client's request or can be obtained from the "Country rates APIs by the country code" field to use - lifeExpectancyFemale |
| annualisedSavingsAcctIntR | Number | Annualised Saving Account Interest Rate | Y | 0.005 | 6 | "savings_account_interest_rate" of a specific country can be used from the Country Rates APIs to populate this field "Country rates APIs by the country code" field to use - savingsAccountInterestRate Default: 0.005 | |
| annualizedInflationRate | Number | Annualized Inflation Rate | Y | 0.03 | 6 | "inflation_rate_long_term" of a specific country can be used from the Country Rates APIs to populate this field "Country rates APIs by the country code" field to use - inflationRateLongTerm Default : 0.03 | |
| compoundsPerYear | Number | Numbers of Compounds Per Year | Y | 1 | >1 | 0 | The number of compounds per year by default to be hardcoded to 1 in the FE. The reason for the CompoundsPeryear field is to convert the interest rate value (Annual Percentage Rate) to the Effective Annual Rate. For more information - https://www.fool.com/knowledge-center/what-are-the-differences-between-apr-ear.aspx Default: 1 |
| period | String | Period | Y | end | 'beg', 'end' | Period can be either of the 2 values only 'beg' or 'end'. 'beg' assumes the first cash infusion starts at the beginning of the first period. 'end' assumes the first cash infusion starts at the ending of the first period. Default : end | |
| country | string | alpha-2 country code | Y | “US” | |||
| additionalSource | dictionary | capture additional source of income that can contribute to retirement | N | additionalSource field is only applicable for country: “US”. It is In Progress for other country | |||
| retirementSavings | Number | The amount of savings for retirement. This parameter assumes a lump-sum amount | Y if additionalSource exist | 10000 | |||
| socialSecurityBenefit | Number | Government-guaranteed monthly retirement income | Y if additionalSource exist | 1500 | |||
| pension | Number | Monthly retirement income from employer | Y if additionalSource exist | 1000 | |||
| colaRate | Number | Cost of Living Adjustment Rate (COLA) is an increase in Social Security benefits to counteract inflation | Y if additionalSource exist | 0.024 | Default value: 0.024 |
Response Data
| Name | DataType | Technical Description | Sample Values | No. of decimals | Notes |
|---|---|---|---|---|---|
| goalAmount | Number | Target amount that user would need for the retirement goal | 1180867.39 | 2 | This is the Lump Sum Amount the user will need to achieve when he retires, defined by the retirement age. If Period = "end": Goal Amount = Annuity If Period = "beg": Goal Amount = Annuity Payment + (Annuity (1 + Inflation Rate)) Annuity Annuity = (Annuity Payment / (Interest Rate - Inflation Rate)) (1 - ( (1 + Inflation Rate) / (1 + Interest Rate) ) ^ Compounding Periods) Annuity Payment Annuity Payment = Annual Retirement Income / Number Of Compounds Per Year |
| totalRetirementExpenditure | Number | Total estimated amount of expenditure required to cover your whole retirement period | 1725470.87 | 2 | |
| workingPeriod | Number | Number of remaining working years until retirement age | 12 | 0 | |
| yearsToDecumulate | Number | No. of years between life expectancy and retirement age | 16 | 0 | The number of years from the day you retire till the day you die. Years To Decumulate = Life Expectancy (f(Gender)) - Retirement Age |
| retirementAssets | Dictionary | List of assets that can cover your retirement | { "totalSocialSecurityBenefits": 314211.14, "totalPension": 217709.92, "totalRetirementSavings": 12682.42, "totalAssets": 544603.48 } | ||
| totalSocialSecurityBenefits | Number | Total amount of Social Security Benefits received from the start of retirement until life expectancy age | 314211.14 | 2 | |
| totalPension | Number | Total amount of pension received during retirement period | 217709.92 | 2 | |
| totalRetirementSavings | Number | Total amount of savings during retirement period | 12682.42 | 2 | |
| totalAssets | Number | Summation of all assets | 544603.48 | 2 |