Services Specification
Purpose
This document outlines optional Morningstar® Retirement ManagerSM capabilities exposed as RESTful services. These are not required for standard onboarding and do not directly replace any existing onboarding requirements.
Please do not use strict validation, for example configuring JSON library to fail on unknown JSON properties. Morningstar reserves the opportunity to add new fields to the JSON response as we enhance and add new capabilities to our system over time.
Access Token
To access the endpoints, client will first need to obtain an access token using OAuth as shown below. NOTE: Each token will be valid for 24 hours.
Obtain Access Token
- UAT URL: https://api-uat.morningstar.com/oauth2/accesstoken
- PROD URL: https://api.morningstar.com/oauth2/accesstoken
- HTTP Method: POST
- Request Headers
- Authorization: Bearer {access_token} (required)
- Content-Type: application/x-www-form-urlencoded
- Request Body
- Key: grant_type; Value: client_credentials (required)
Express Enroll
Express Enroll API directly exposes enrollment portion of Morningstar® Retirement ManagerSM functionality enabling clients to integrate real time participant enrollment into their participant interfaces, internal systems and operational processes. API returns fund allocation recommendations
Overview
Functionality will be exposed in a form of an externally accessible synchronous RESTful endpoint.
Input:
- Client Id (required)
- Participant XML (required)
- Retirement Age (optional)
- Savings rates (optional)
- Salary (optional)
- Pensions (optional)
- Exclude Social Security (optional)
- DOB(optional)
- Gender(optional)
- State Of Residence(optional)
- Desired Retirement Income (optional)
- Enrollment info (required)
- Forecast type (optional)
- Transaction HTTP Endpoint (optional)
Output (success):
- Enrollment Result
- Strategy
- Transaction XML encoded
Output (error):
- Error object
Invoke Express Enroll
- UAT URL: https://api-uat.morningstar.com/rm/v1/express/enroll
- PROD URL: https://api.morningstar.com/rm/v1/express/enroll
- Request Headers:
- Content-Type: application/json (required)
- Authorization: Bearer {access_token}
Sample Request Payload
{
"ClientId": "ABCD",
"DesiredRetirementIncome": {
"Type": "0",
"Value": "100"
},
"DOB": "2020-11-04T18:44:12.301Z",
"EnrollmentInfo": [
{
"PlanId": "planId",
"PlanType": "Plan Type",
"ServiceOption": "ManagedAccounts"
}
],
"ExcludeSocialSecurity": true,
"Gender": "F",
"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"
}
],
"StateOfResidence": "IL",
"ForecastType":"Revised",
"TransactionHTTPEndpoint":
{
"TransURL": "https://www.test.com/gettransaction",
"SID": "sdhgjkjhgfdgujytrfrthwfwdfter",
"Cookie": "wesrtdfgyuhjkftdtyg"
}
}
Sample Success Response Data points
{
"EnrollmentResult": {
"Success": true,
"ErrorMessage": "",
"TransactionId": "123",
"ClientTransactionId": "456",
"RKTransactionId": "789",
"RKTransactionMessage": "",
"TransactionState": "",
"TransactionReturnCode": "",
"TransactionData": "",
"HtmlTransactionConfirmation": true,
"ClientId": "ABCD",
"AnnuityPurchaseRequest": null
},
"Strategy":
{
"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": "Type",
"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
}
]
}
}
],
"AccountMappings": [
{
"AccountId": "UNIQUEIDENTIFIER",
"PlanId": "planId",
"PlanType": "Plan Type"
}
],
} ,
"Transaction": "ENCODED TRANSACTION XML"
}
Input Data Points
Output Data Points
Express Optout
Overview
Functionality will be exposed in a form of an externally accessible synchronous RESTful endpoint.
Input:
- Client Id (required)
- Participant ID (required)
- FirstName (required)
- LastName (required)
- Optout info (required)
- Reason (optional)
- Transaction HTTP Endpoint (optional)
Output (success):
- Optout Result
Output (error):
- Error object
Invoke Optout
- UAT URL: https://api-uat.morningstar.com/rm/v1/express/optout
- PROD URL: https://api.morningstar.com/rm/v1/express/optout
- Request Headers:
- Content-Type: application/json (required)
- Authorization: Bearer {access_token}
Sample Request Payload
{
"ClientId": "ABCD",
"FirstName": "First Name",
"LastName": "Last Name",
"OptoutInfo": [
{
"PlanId": "planId",
"PlanType": "Plan Type"
}
],
"ParticipantId": "articipant Id (UserID)",
"TransactionHTTPEndpoint":
{
"TransURL": "https://www.test.com/gettransaction",
"SID": "sdhgjkjhgfdgujytrfrthwfwdfter",
"Cookie": "wesrtdfgyuhjkftdtyg"
}
}
Sample Success Response Data points
{
"OptOutResult": {
"Success": true,
"ErrorMessage": "",
"TransactionId": "123",
"ClientTransactionId": "456",
"RKTransactionId": "789",
"RKTransactionMessage": "",
"TransactionState": "",
"TransactionReturnCode": "",
"TransactionData": "",
"HtmlTransactionConfirmation": true,
"ClientId": "ABCD"
},
"Transaction": "ENCODED TRANSACTION XML"
}
Input Data Points
Output Data Points
Express Implement
Express Enroll Implement API directly exposes rebalance/realloaction portion of Morningstar® Retirement ManagerSM functionality enabling clients to integrate real time participant rebalance into their participant interfaces, internal systems and operational processes. API returns fund allocation recommendations
Overview
Functionality will be exposed in a form of an externally accessible synchronous RESTful endpoint.
Input:
- Client Id (required)
- Participant XML (required)
- Retirement Age (optional)
- Savings rates (optional)
- Salary (optional)
- Pensions (optional)
- Exclude Social Security (optional)
- DOB(optional)
- Gender(optional)
- State Of Residence(optional)
- Desired Retirement Income (optional)
- Enrollment info (required)
- Transaction HTTP Endpoint (optional)
Output (success):
- Enrollment Result
- Strategy
- Transaction XML encoded
Output (error):
- Error object
Invoke Express Implement
- UAT URL: https://api-uat.morningstar.com/rm/v1/express/enroll/implement
- PROD URL: https://api.morningstar.com/rm/v1/express/enroll/implement
- Request Headers:
- Content-Type: application/json (required)
- Authorization: Bearer {access_token}
Sample Request Payload
{
"ClientId": "ABCD",
"DesiredRetirementIncome": {
"Type": "0",
"Value": "100"
},
"DOB": "2020-11-04T18:44:12.301Z",
"EnrollmentInfo": [
{
"PlanId": "planId",
"PlanType": "Plan Type",
"ServiceOption": "ManagedAccounts"
}
],
"ExcludeSocialSecurity": true,
"Gender": "F",
"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"
}
],
"StateOfResidence": "IL",
"ForecastType":"Revised",
"TransactionHTTPEndpoint":
{
"TransURL": "https://www.test.com/gettransaction",
"SID": "sdhgjkjhgfdgujytrfrthwfwdfter",
"Cookie": "wesrtdfgyuhjkftdtyg"
}
}
Sample Success Response Data points
{
"EnrollmentResult": {
"Success": true,
"ErrorMessage": "",
"TransactionId": "123",
"ClientTransactionId": "456",
"RKTransactionId": "789",
"RKTransactionMessage": "",
"TransactionState": "",
"TransactionReturnCode": "",
"TransactionData": "",
"HtmlTransactionConfirmation": true,
"ClientId": "ABCD",
"AnnuityPurchaseRequest": null
},
"Strategy":
{
"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": "Type",
"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
}
]
}
}
],
"AccountMappings": [
{
"AccountId": "UNIQUEIDENTIFIER",
"PlanId": "planId",
"PlanType": "Plan Type"
}
],
} ,
"Transaction": "ENCODED TRANSACTION XML"
}
Input Data Points
Output Data Points
Express Forecast
Express Forecast API directly exposes forecasting portion of Morningstar® Retirement ManagerSM 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:
- Client Id (required)
- Participant XML (required)
- Retirement Age (optional)
- Savings rates (optional)
- Salary (optional)
- Pensions (optional)
- Exclude Social Security (optional)
- Forecast type (optional)
Output (success):
- RM Strategy Output DTO instance that contains strategy Output object array, one for each applicable strategy
- Transaction XML encoded
Output (error):
- Error object
Invoke Express Forecast
- UAT URL: https://api-uat.morningstar.com/rm/v1/express/forecast
- PROD URL: https://api.morningstar.com/rm/v1/express/forecast
- Request Headers:
- Content-Type: application/json (required)
- Authorization: Bearer {access_token}
Sample 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"
}
Sample Success Response Data points
{
"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"
}
],
}
Input Data Points
Output Data Points
Express Forecast Case Information
The Forecast Case Information API is a specialized endpoint that provides essential retirement planning details without requiring a complete participant profile. This streamlined service allows you to retrieve personalized Social Security benefit estimates and life expectancy projections based on minimal demographic information.This API offers a streamlined alternative to the more comprehensive Express Forecast endpoint
Overview
Functionality will be exposed in a form of an externally accessible synchronous RESTful endpoint.
- Input:
- Salary (required)
- Retirement Age (required)
- Client Id (required)
- Date of Birth (required)
- Gender (optional)
- Social Security Age Override (optional)
- Output (success):
- Forecast caseinformation Output DTO instance that contains Social Security and Life Expentancy Output object array, one for each applicable Social Security Age
- Output (error):
- Error object
Invoke Express Forecast Case Information
- UAT URL: https://api-uat.morningstar.com/rm/v1/express/forecast/caseinformation
- PROD URL: https://api.morningstar.com/rm/v1/express/forecast/caseinformation
- Request Headers:
- Content-Type: application/json (required)
- Authorization: Bearer {access_token}
Sample Request Payload
{
"Salary": "70000",
"RetirementAge": "67",
"ClientId": "DEVP50",
"DOB": "1970-01-22",
"Gender":"F",
"SSAgeOverride":[65,67]
}
Sample Success Response Data points
{
"SocialSecurity": [
{
"Age": 65,
"Amount": 6013.661276,
"PenaltyAmount": 20792.890498
},
{
"Age": 67,
"Amount": 30930.63665,
"PenaltyAmount": 0.0
}
],
"LifeExpectancy": {
"Age": 94
}
}
Input Data Points
Output Data Points
Express Forecast Current
Express Forecast Current API directly exposes current forecasting portion of Morningstar® Retirement ManagerSM 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.
Current Strategy will tell the participant how their account is doing relative to their retirement need, but will not give advice.
Overview
Functionality will be exposed in a form of an externally accessible synchronous RESTful endpoint.
Input:
- Client Id (required)
- Participant XML (required)
- Retirement Age (optional)
- Savings rates (optional)
- Salary (optional)
- Pensions (optional)
- Exclude Social Security (optional)
Output (success):
- RM Strategy Output DTO instance that contains strategy Output object array, one for each applicable strategy
- Transaction XML encoded
Output (error):
- Error object
Invoke Express Forecast Current
- UAT URL: https://api-uat.morningstar.com/rm/v1/express/forecast/current
- PROD URL: https://api.morningstar.com/rm/v1/express/forecast/current
- Request Headers:
- Content-Type: application/json (required)
- Authorization: Bearer {access_token}
Sample 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"
}
]
}
Sample Success Response Data points
{
"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"
}
],
}