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.
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)
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",**
**"ParticipantXML": "RM Participant XML ",**
"RetirementAge": 71,
"SavingsRateDetails": [
{
"PlanId": "XYZ_PLAN",
"SavingsType": “0”,
"Value": “0”
}
],
"Salary": 75000,
"PensionTypes": [
{
"Amount": 13000,
"StartYear": "2021",
"IsFromRecordKeeper": true,
"Cola": true
}
],
"ExcludeSocialSecurity": true ,
"DOB": "2020-11-04T18:44:12.301Z",
"Gender": “F”,
"StateOfResidence": "IL",
"DesiredRetirementIncome":
{
"Value": “100”,
"Type": “0”
},
"EnrollmentInfo":[
{
"PlanId":"planId",
"PlanType": "Plan Type"
}
]
}
Sample Success Response Payload
{
"EnrollmentResult": {
"Success": true,
"ErrorMessage": "",
"TransactionId": "123",
"ClientTransactionId": "456",
"RKTransactionId": "789",
"RKTransactionMessage": "",
"TransactionState": "",
"TransactionReturnCode": "",
"TransactionData": "",
"HtmlTransactionConfirmation": true,
"ClientId": "ABCD"
},
“Strategy”:”Strategy results”,
"Transaction": "ENCODED TRANSACTION XML"
}
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)
Output (success):
- RM Strategy Output DTO instance that contains
- Strategy Output object array, one for each applicable strategy
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",
ParticipantXML": "RM Participant XML ",
"RetirementAge": 71,
"SavingsRateDetails": [
{
"PlanId": "XYZ_PLAN",
"SavingsType": “0”,
"Value": “0”
}
],
"Salary": 75000,
"PensionTypes": [
{
"Amount": 13000,
"StartYear": "2021",
"IsFromRecordKeeper": true,
"Cola": true
}
],
"ExcludeSocialSecurity": true
}
Sample Success Response Payload
{
"StrategyOutput": [
],
}
Express Optout
Optout API directly exposes optout (Cancel service) functionality enabling clients to cancel service from Managed Accounts from their participant interfaces. It returns Optout results .
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)
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",
"ParticipantId": : “Participant Id (UserID)",
"FirstName":"Frist Name",
"LastName": "Last Name",
" OptoutInfo":[
{
"PlanId":"planId",
"PlanType": "Plan Type"
}
]
}
Sample Success Response Payload
{
"OptOutResult": {
"Success": true,
"ErrorMessage": "",
"TransactionId": "123",
"ClientTransactionId": "456",
"RKTransactionId": "789",
"RKTransactionMessage": "",
"TransactionState": "",
"TransactionReturnCode": "",
"TransactionData": "",
"HtmlTransactionConfirmation": true,
"ClientId": "ABCD"
},
"Transaction": "ENCODED TRANSACTION XML"
}
Service Exposure
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)