Express Forecast
Express Forecast API directly exposes forecasting portion of Morningstar® Retirement Manager™ functionality enabling clients to integrate forecasting tools into their participant interfaces.
API utilizes record-kept participant data and provides:
Income projections based on participant’s current strategy. This assumes a default retirement age, per RM logic.
Income Projections asset and fund allocation based on user provided inputs (listed below)
Overview
Functionality will be exposed in a form of an externally accessible synchronous RESTful endpoint.
Input Parameters
Required Parameters
These parameters are mandatory for successful forecasting:
- Client Id: Your organization identifier
- Participant XML: Complete RM Participant XML data
| Parameter | Required | Description |
|---|---|---|
| Client Id | required | Your organization identifier |
| Participant XML | required | RM Participant XML data |
| Retirement Age | optional | Retirement age |
| Savings rates | optional | Savings rate details |
| Salary | optional | Salary details |
| Pensions | optional | Pension information |
| Exclude Social Security | optional | Whether to exclude Social Security |
| Forecast type | optional | Type of forecast |
Output (Success)
| Field | Description |
|---|---|
| StrategyOutput | RM Strategy Output DTO instance containing strategy output objects |
| Transaction XML | Transaction data |
Output (Error)
| Field | Description |
|---|---|
| Error Object | Error details and messages |
API Endpoint
Invoke Express Forecast
UAT
POST https://api-uat.morningstar.com/rm/v1/express/forecast
Production
POST https://api.morningstar.com/rm/v1/express/forecast
Request Headers
Required Headers
Content-Type: application/json
Authorization: Bearer {access_token}
Sample Requests & Responses
Request Payload
{
"ClientId": "ABCD",
"ExcludeSocialSecurity": true,
"ParticipantXML": "RM Participant XML",
"PensionTypes": [
{
"Amount": 13000,
"Cola": true,
"IsFromRecordKeeper": true,
"StartYear": "2021"
}
],
"RetirementAge": 71,
"Salary": 75000,
"SavingsRateDetails": [
{
"PlanId": "XYZ_PLAN",
"SavingsType": "0",
"Value": "0"
}
],
"ForecastType": "Revised"
}
Success Response
{
"StrategyOutput": [
{
"InvestmentSelections": {
"--UNIQUEIDENTIFIER--": []
},
"AssetMixAdvisableAccounts": {
"--UNIQUEIDENTIFIER--": {
"Asset": [
{
"AssetClass": "LargeCap",
"Weight": "20"
}
],
"RiskLevel": "3"
}
},
"AssetMixHousehold": {
"Asset": [
{
"AssetClass": "LargeCap",
"Weight": "31"
}
],
"RiskLevel": "3"
},
"AssetMixOverall": {
"Asset": [],
"RiskLevel": ""
},
"AssetMixOther": [
{
"AssetMix": {
"Asset": [
{
"AssetClass": "LargeCap",
"Weight": "24.724200"
}
],
"RiskLevel": "3"
},
"Id": "RMDefaultTaxableAccount"
}
],
"BalanceHistory": {
"--UNIQUEIDENTIFIER--": []
},
"HistoricalScenarios": [
{
"Balance": [
{
"Year": "2025",
"Month": "2",
"Value": 0.00,
"BenchmarkValue": 0.0000
},
{
"Year": "2025",
"Month": "3",
"Value": 0.0000,
"BenchmarkValue": 0.00000000
}
],
"Name": "Name",
"BenchmarkName": "BName"
}
],
"Percentile": [
{
"IncomeSources": [
{
"Values": [
{
"Age": "50",
"Value": 0.0
}
],
"Type": "AccountIncome",
"Account": "RMDefaultTaxableAccount",
"Investor": "Participant",
"ContributionType": "PostTax",
"CatchupType": "Type"
}
],
"TotalWealth": {
"Values": [
{
"Age": "50",
"Value": 0.0
}
]
},
"OverallEndingBalance": {
"Values": [
{
"Age": "50",
"Value": 0.0
}
]
},
"Taxes": {
"Values": [
{
"Age": "50",
"Value": 0.0
}
]
},
"RetirementIncomeAtVariousRetirementAges": [],
"Percentage": 50.0,
"Label": "Strong Market",
"SustainableRetirementIncome": 0.0,
"AccountBalance": [
{
"Values": [
{
"Age": "50",
"Value": 0.0
}
],
"Type": "BeginingBalance",
"Account": "RMDefaultTaxableAccount",
"Investor": "Participant",
"ContributionType": "PostTax",
"CatchupType": "Type"
},
{
"Values": [
{
"Age": "50",
"Value": 0.0
}
],
"Type": "BeginingBalance",
"Account": "--UNIQUEIDENTIFIER--",
"Investor": "Participant",
"ContributionType": "PostTax",
"CatchupType": "Type"
}
]
}
],
"SavingsRateDetail": [
{
"SavingsComponent": [
{
"PlanId": "ID",
"Type": "Pretax",
"Value": 0.0,
"IsRoth": false,
"NumberOfYears": 0,
"DollarAmount": 0.0
}
],
"Account": "--UNIQUEIDENTIFIER--"
}
],
"AccountSavingsRateDetail": [
{
"SavingsComponent": [
{
"PlanId": "ID",
"Type": "Pretax",
"Value": 0.0,
"IsRoth": false,
"NumberOfYears": 0,
"DollarAmount": 0.0
}
],
"Account": "--UNIQUEIDENTIFIER--"
}
],
"CSSellOffData": [],
"StrategyType": "Current",
"Rating": "3",
"RiskLevel": "3",
"RetirementAge": "65",
"RetirementSpouse": "",
"SavingsRate": 0.0,
"NetRetirementIncomeGoalParticipant": 0.0,
"NetRetirementIncomeGoal": 0.0,
"SocialSecurity": [
{
"Age": "67",
"FullBenefitAge": 67,
"Amount": 0.0,
"GrossAmount": 0.0,
"FullBenefitAmount": 0.0,
"Account": "--UNIQUEIDENTIFIER--",
"Investor": "Participant"
}
],
"ModelPortfolioIndex": 4,
"SavingsRateTaxableOverflow": {
"Value": 0.0,
"DollarAmount": 0.0
},
"SavingsRateOverall": {
"Value": 0.0,
"DollarAmount": 0.0
},
"RisOutput": {
"AnnuityType": "GMWB",
"Recommendations": [
{
"AnnuityType": "GMWB",
"LoweringAnnuitizationAdvisable": true,
"Percentage": 0.12064,
"Amount": 0.0
}
]
}
},
{
"InvestmentSelections": {
"--UNIQUEIDENTIFIER--": []
},
"AssetMixAdvisableAccounts": {
"--UNIQUEIDENTIFIER--": {
"Asset": [
{
"AssetClass": "LargeCap",
"Weight": "20"
}
],
"RiskLevel": "3"
}
},
"AssetMixHousehold": {
"Asset": [
{
"AssetClass": "LargeCap",
"Weight": "31"
}
],
"RiskLevel": "3"
},
"AssetMixOverall": {
"Asset": [],
"RiskLevel": ""
},
"AssetMixOther": [
{
"AssetMix": {
"Asset": [
{
"AssetClass": "LargeCap",
"Weight": "24.724200"
}
],
"RiskLevel": "3"
},
"Id": "RMDefaultTaxableAccount"
}
],
"BalanceHistory": {
"--UNIQUEIDENTIFIER--": []
},
"HistoricalScenarios": [
{
"Balance": [
{
"Year": "2025",
"Month": "2",
"Value": 0.00,
"BenchmarkValue": 0.0000
},
{
"Year": "2025",
"Month": "3",
"Value": 0.0000,
"BenchmarkValue": 0.00000000
}
],
"Name": "Name",
"BenchmarkName": "BName"
}
],
"Percentile": [
{
"IncomeSources": [
{
"Values": [
{
"Age": "50",
"Value": 0.0
}
],
"Type": "AccountIncome",
"Account": "RMDefaultTaxableAccount",
"Investor": "Participant",
"ContributionType": "PostTax",
"CatchupType": "Type"
}
],
"TotalWealth": {
"Values": [
{
"Age": "50",
"Value": 0.0
}
]
},
"OverallEndingBalance": {
"Values": [
{
"Age": "50",
"Value": 0.0
}
]
},
"Taxes": {
"Values": [
{
"Age": "50",
"Value": 0.0
}
]
},
"RetirementIncomeAtVariousRetirementAges": [],
"Percentage": 50.0,
"Label": "Strong Market",
"SustainableRetirementIncome": 0.0,
"AccountBalance": [
{
"Values": [
{
"Age": "50",
"Value": 0.0
}
],
"Type": "BeginingBalance",
"Account": "RMDefaultTaxableAccount",
"Investor": "Participant",
"ContributionType": "PostTax",
"CatchupType": "Type"
},
{
"Values": [
{
"Age": "50",
"Value": 0.0
}
],
"Type": "BeginingBalance",
"Account": "--UNIQUEIDENTIFIER--",
"Investor": "Participant",
"ContributionType": "PostTax",
"CatchupType": "Type"
}
]
}
],
"SavingsRateDetail": [
{
"SavingsComponent": [
{
"PlanId": "ID",
"Type": "Pretax",
"Value": 0.0,
"IsRoth": false,
"NumberOfYears": 0,
"DollarAmount": 0.0
}
],
"Account": "--UNIQUEIDENTIFIER--"
}
],
"AccountSavingsRateDetail": [
{
"SavingsComponent": [
{
"PlanId": "ID",
"Type": "Pretax",
"Value": 0.0,
"IsRoth": false,
"NumberOfYears": 0,
"DollarAmount": 0.0
}
],
"Account": "--UNIQUEIDENTIFIER--"
}
],
"CSSellOffData": [],
"StrategyType": "Revised",
"Rating": "4",
"RiskLevel": "4",
"RetirementAge": "65",
"RetirementSpouse": "",
"SavingsRate": 0.0,
"NetRetirementIncomeGoalParticipant": 0.0,
"NetRetirementIncomeGoal": 0.0,
"SocialSecurity": [
{
"Age": "67",
"FullBenefitAge": 67,
"Amount": 0.0,
"GrossAmount": 0.0,
"FullBenefitAmount": 0.0,
"Account": "--UNIQUEIDENTIFIER--",
"Investor": "Participant"
}
],
"ModelPortfolioIndex": 3,
"SavingsRateTaxableOverflow": {
"Value": 0.0,
"DollarAmount": 0.0
},
"SavingsRateOverall": {
"Value": 0.0,
"DollarAmount": 0.0
},
"RisOutput": {
"AnnuityType": "GMWB",
"Recommendations": [
{
"AnnuityType": "GMWB",
"LoweringAnnuitizationAdvisable": true,
"Percentage": 0.12064,
"Amount": 0.0
}
]
}
}
],
"CommunicationXML": "ENCODED TRANSACTION XML",
"AccountMappings": [
{
"AccountId": "UNIQUEIDENTIFIER",
"PlanId": "planId",
"PlanType": "Plan Type"
}
]
}
Data Tables
Input Data Points
Total: 0Required: 0Optional: 0Showing: 0
Parameter | Type | Required | Description | Example |
|---|
No parameters found
No parameters found
Output Data Points
Total: 0Showing: 0
Parameter | Type | Description | Example |
|---|
No parameters found
No parameters found