Retirement

This walkthrough demonstrates how a client in the US creates a retirement goal and how retirement API enables this functionality. The retirement API has features specialized to cater retirement use cases in the US, such as Social Security Benefits and expenditure data based on geographical location as age group in US.

In this walkthrough, we will start gathering information about the client’s retirement plan, age, savings, and location.

We can see on this page that the client has an option to plan for “Myself” or “Myself and with my partner”. Currently, the new version of the API is able to calculate the retirement goal amount for “Myself”. Meanwhile, for “Myself and with my partner” option, we are formulating the algorithm in order to calculate the retirement goal amount accurately for a couple. This particular feature is under development and not available in API Library yet.

There are some clients who have already planned for their retirement. In this page, there is a field where they can indicate whether they know how much they need to save for their retirement. For those clients, they can choose “Yes” and they will be prompted to fill in the retirement goal amount in the next step.

Retirement API is intended to cater for clients who have never thought about retirement planning. In this walkthrough, we will go through the journey where they choose “No” on the “how much they need to save for their retirement” field and click “Continue” after filling up all the fields.

We then go to the lifestyle preference options page

Retirement goal helper accepts lifestyle categories and the value of each category. Here is the list of all categories:

  1. "Alcoholic Beverages",
  2. "Apparel and Services",
  3. "Cash Contributions",
  4. "Education",
  5. "Entertainment",
  6. "Food",
  7. "Healthcare",
  8. "Housing",
  9. "Miscellaneous",
  10. "Personal Care Products and Services",
  11. "Personal Insurance and Pensions",
  12. "Reading",
  13. "Tobacco Products and Smoking Supplies",
  14. "Transportation"

Each category has band ranges from 1 to 10 and the higher the band, the higher the amount.

In the lifestyle preference page, we ask top 5 categories (that covers 75% of total expenditure based on our research) where the client has the ability to choose based on his preferences. The remaining categories fall under “Miscellaneous”. There is a slider with 5 points - from basic to luxurious - in each category, and each point in the slider represents band 1, 3, 5, 7 and 9. To obtain the expenditure amount per category, we are calling 2 APIs:

  1. GET api/country/v2/getUsaStates
    This API returns a list of regions, divisions and states in the US. There is an option to do filtering to return filtered response payload. For this example, we will call this API and filter based on state value, which is “South Dakota”
[
    {
        "region": "Midwest",
        "division": "West North Central",
        "state": "South Dakota"
    }
]

Based on the client’s retirement location, we will map it to get the value of region which will be passed on the next API.

  1. POST /api/generalCalculator/v2/retirements/expenditures/futureAmount
    This API returns a list of the expenditure amount per category in future dollars for all bands based on client’s choices. This is the following request payload for this API:
{
  "country": "US",
  "region": "Midwest",
  "currentYear": 2021,
  "age": 32,
  "retirementAge": 61,
  "inflationRate": 0.017
}

And this is the response payload:

{
  "yearsToRetirement": 29,
  "retirementYear": 2050,
  "futureExpenditures": [
    {
      "expenditures": "Housing",
      "band": 1,
      "amount": 812,
      "currency": "USD",
      "ageRange": "65 and above",
      "region": "Midwest"
    },
    …
    {
      "expenditures": "Housing",
      "band": 10,
      "amount": 4737.19,
      "currency": "USD",
      "ageRange": "65 and above",
      "region": "Midwest"
    },
      …
    {
      "expenditures": "Transportation",
      "band": 1,
      "amount": 374.99,
      "currency": "USD",
      "ageRange": "65 and above",
      "region": "Midwest"
    }
  ]
}

Based on the slider which represents the band, the value from the “amount” field will be used to display the monthly expense for each category in the lifestyle preference page. At the bottom of the UI above, “Miscellaneous” category is basically the summation of remaining categories of the same band.

In the slider, there is a “recommended range” where the recommendation is based on the client's income. We can obtain it from the following API where it returns the income band of the client:

GET /api/generalCalculator/v2/retirements/incomeBands
Here is the response payload:

{
    "incomeBand": 5
}

We can see that in the UI above, the client can see projected monthly retirement expenses in future dollars displayed at the top. The projected monthly retirement expense value is the summation of the future amount of all categories of selected band from POST /api/generalCalculator/v2/retirements/expenditures/futureAmount API. When the client changes one of the lifestyle preferences, the projected amount at the top changes accordingly.

For example in the UI above when the client chooses option 1 for “Housing” the amount for that option in that category is 1097.08 USD and that amount will be accumulated with other amounts as the total projected amount at the top. If the client changes the “Housing” option from 1 to 3, the category will then take the new amount and the total projected amount will change accordingly.

After the client has filled in the lifestyle preferences and is satisfied with the monthly retirement expenses at the top, we proceed to the next step which is to input additional income sources.

In Additional Income Source page, the client will fill up 3 following fields:

  1. Current retirement savings
  2. Social Security Benefits
  3. Defined benefit or contribution payout

For the Social Security Benefits field, currently we are developing an algorithm to calculate Social Security Benefits based on the client's profile and it is not yet available in retirement API.

After filling up all the information regarding additional income sources, the client can click “Continue” to proceed to the retirement goal amount summary page where we can see how much retirement amount the client needs to save and invest.

In this retirement goal amount summary page, the monthly retirement assets amount on the left hand side is the same projected amount in the lifestyle preference step. The amount the client is on track to have on the right hand side is the sum of monthly pension and social security benefit the client inputted in the additional income source step. The amount the client needs to prepare is the projected amount subtracted with the amount the client is on track to have.

In the middle we have the amount of total retirement assets. We receive that from this API which calculates the retirement goal amount as well as the retirement assets:

POST /api/generalCalculator/v2/goalCalculator/calcRetirementGoalAmount
using this input parameters gathered from client’s choices from the previous steps:

{
    "annualRetirementIncome": 123000, // (monthly retirement expense x 12)
    "age": 32,
    "retirementAge": 61,
    "gender": "Male",
    "lifeExpectancyMale": 81,  // (the library has an API to get this)
    "lifeExpectancyFemale": 86,  // (the library has an API to get this)
    "annualisedSavingsAcctIntR": 0.02, // (annualised saving account interest rate, the library has an API to get this)
    "annualisedInflationRate": 0.017, // (the library has an API to get this)
    "compoundsPerYear": 1,
    "period": "end",
    "country": "US",
    "additionalSource": {
        "retirementSavings": 10000, // (inputted from the first step)
        "socialSecurityBenefit": 1900, // (monthly, inputted from the first step)
        "pension": 1000,  // (monthly, inputted from the first step)
        "colaRate": 0.024  // (constant value of 0.024, cost of living adjustment)
    }
}

This is response payload:

{
    "goalAmount": 1800000, // (amount of total retirement assets)
    "totalRetirementExpenditure": 2344603.48,
    "retirementAssets": {
        "totalSocialSecurityBenefits": 314211.14,
        "totalPension": 217709.92,
        "totalRetirementSavings": 12682.42,
        "totalAssets": 544603.48
    },
    "workingPeriod": 29,
    "yearsToDecumulate": 20
}

That concludes a walkthrough of retirement API.

Updated 8 months ago


Retirement


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.