GRAIL 1.0.9
Guaranteed Retirement Analytics For Income And Legacy
API DESCRIPTION
The GRAIL API provides analytics for retirement portfolios.
The portfolio analytics revolve around 3 central questions:
1:Is a guarantee required in a retirement portfolio based on its goals?
2:If so, which guaranteed product(s) match the retirement portfolio requirements?
3:How much of the portfolio should be invested in the guaranteed product?
The GRAIL API takes demographic, market, and guaranteed product data as inputs to generate various outputs that help with decisions about retirement portfolios.
API GENERAL INFORMATION
GRAIL is a REST-based API that uses JSON
for the exchange of data and uses standard HTTP
verbs to represent its actions.
API SECURITY
Infrastructure Security
1: Client Application IP is whitelisted i.e., source IP address is provided to AWS Network Security Group for secure communication.
2: Client has access to GRAIL REST API based on industry standard https protocol.
Application Security
1: Authentication using HTTP Basic Auth.
2: Authorization Token.
Data Security
1: Data Encryption and Decryption at Payload level or field Level is provided based on requirements.
2: Client and Hedgeness share RSA based on public and private keys.
API ARCHITECTURE

API AUTHENTICATION
Access Token URL
is the endpoint for authentication server:
The method to get a token to be used in the header is based on Client Credentials that comprise a Client ID
and a Client Secret which will be provided by Hedgeness during the Client registration process.
url https://qa-analytics-hedgenessfin
-qa02.auth.us-east-2
.amazoncognito.com/oauth2/token \
API HEADERS
The following HTTP header(s) are required when calling GRAIL endpoints:
Authorization: Bearer Token
Content-type: application/json
This header specifies that the data provided in input to the endpoint is in JSON format
API RESPONSE CODES
Code |
Status |
Description |
200 |
OK |
The request was successfully completed. |
400 |
Bad Request |
The request was invalid. |
401 |
Unauthorized |
The request did not include an authentication token or the authentication token expired. |
403 |
Forbidden |
The client did not have permission to access the requested resource. |
404 |
Not Found |
The requested resource was not found. |
405 |
Method Not Allowed |
The HTTP method in the request was not supported by the resource. |
500 |
Internal Server Error |
The request was not completed due to an internal error on the server side. |
503 |
Service Unavailable |
The server was unavailable. |
API REGIONS
GRAIL API servers are located in the United States of America.
Per Client request, GRAIL can be deployed in other regions.
API OPERATIONS OVERVIEW

DESCRIPTION
The Average Returns operation for Non-Guaranteed Portfolio calculates the portfolio’sSMART IRR. SMART
stands for “Single Measure of Accomplished Retirement Terms” and is calculated in the following manner for a Non-Guaranteed Portfolio:
(1)
If a non-guaranteed portfolio runs out of money, additional funds are brought into the account to cover any income shortfalls, and (2)
SMART IRR is calculated by using the initial investment, the income withdrawals, any additional funds to cover income shortfalls, and the residual value at the end of the period
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Non-Guaranteed or Guaranteed |
Must be "NG" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementNG",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "false",,
"lowest_income_distribution_flag": "false",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "true",,
"chart_data_flag": "false",,
"requestData": :[
{
"account_type": ":NG",,
"account_value": ":1000000",,
"income_withdrawal": ":40000",
"years_to_retirement": :5,,
"retirement_duration": :35,,
"underlying_fees": : 0.006,
},
"advisor_fees": : 0.01,,
"stock_percentage": : 0.35,
"bond_percentage": 0.65
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
smart_irr |
Number |
SMART stands for “Single Measure of Accomplished Retirement Terms” and is calculated in the following manner:
1. If a non-guaranteed portfolio runs out of money, additional funds are brought into the account to cover any income shortfalls.
2. A guaranteed portfolio continues to pay out the guaranteed income even if account value goes to zero.
3. SMART IRR is calculated by using the initial investment, the income withdrawals, any additional funds to cover income shortfalls, and the residual value at the end of the period.
|
API RESPONSE BODY EXAMPLE
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"smart_irr": 5.1099666816508496
}
]
}
DESCRIPTION
The Average Returns operation for Guaranteed Portfolio calculates the portfolio’sSMART IRR. SMART
stands for “Single Measure of Accomplished Retirement Terms” and is calculated in the following manner for a Guaranteed Portfolio:
(1)
A guaranteed portfolio continues to pay out the guaranteed income even if account value goes to zero, and (2)
SMART IRR is calculated by using the initial investment, the income withdrawals, any additional funds to cover income shortfalls, and the residual value at the end of the period.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "G" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementNG",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "false",,
"lowest_income_distribution_flag": "false",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "true",,
"chart_data_flag": "false",,
"requestData": :[
{
"account_type": ":G",,
"account_value": ":1000000",,
"income_withdrawal": ":65000",
"years_to_retirement": :5,
"retirement_duration": :35,
"stock_percentage": : 0.8,
"bond_percentage": : 0.2,
"glwb_rider_fee": :0.0125,,
"sub_account_fund_fees" :0.006,
},
"m&e&a_fees": : 0.002,,
"advisor_fees": : 0.01,
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
smart_irr |
Number |
SMART stands for “Single Measure of Accomplished Retirement Terms” and is calculated in the following manner: 1. If a non-guaranteed portfolio runs out of money, additional funds are brought into the account to cover any income shortfalls. 2. A guaranteed portfolio continues to pay out the guaranteed income even if account value goes to zero. 3. SMART IRR is calculated by using the initial investment, the income withdrawals, any additional funds to cover income shortfalls, and the residual value at the end of the period.
|
BODY EXAMPLE
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"smart_irr": 6.762029344312061
}
]
}
DESCRIPTION
The Average Returns operation for Non-Guaranteed Portfolio calculates the portfolio’sSMART IRR. SMART
stands for “Single Measure of Accomplished Retirement Terms” and is calculated in the following manner for (I) the Non-Guaranteed portion of the Combined Portfolio:
(1)
If a non-guaranteed portfolio runs out of money, additional funds are brought into the account to cover any income shortfalls, and(2)
SMART IRR is calculated by using the initial investment, the income withdrawals, any additional funds to cover income shortfalls, and the residual value at the end of the period; and in the following manner for (II) the Guaranteed portion of the Combined Portfolio: (1) A guaranteed portfolio continues to pay out the guaranteed income even if account value goes to zero, and (2) SMART IRR is calculated by using the initial investment, the income withdrawals, any additional funds to cover income shortfalls, and the residual value at the end of the period.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "NG" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementCombo",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "false",,
"lowest_income_distribution_flag": "false",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "true",,
"chart_data_flag": "false",
"ng_and_g_common_parameters": :{
"years_to_retirement": "5",
"retirement_duration": "35",
}
"requestData": :[
{
"account_type": ":NG",
"account_value": ":300000",
"income_withdrawal": ":0",
"underlying_fees": :"0.006"
"advisor_fees": :"0.01",
"stock_percentage": : 1,
"bond_percentage": : 0,
},{
"account_type": "G",
"account_value": "700000",
"income_withdrawal": "45000",
"stock_percentage": "0.8",
"bond_percentage": "0.2",
"glwb_rider_fee": "0.0125",
"sub_account_fund_fees": "0.005",
"m&e&a_fees": "0.002",
"advisor_fees": "0.01"
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
smart_irr |
Number |
SMART stands for “Single Measure of Accomplished Retirement Terms” and is calculated in the following manner: 1. If a non-guaranteed portfolio runs out of money, additional funds are brought into the account to cover any income shortfalls. 2. A guaranteed portfolio continues to pay out the guaranteed income even if account value goes to zero. 3. SMART IRR is calculated by using the initial investment, the income withdrawals, any additional funds to cover income shortfalls, and the residual value at the end of the period.
|
API RESPONSE BODY EXAMPLE
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"smart_irr": 7.023355993762932
}
]
}
DESCRIPTION
The Income Probabilities operation for Non-Guaranteed Portfolio calculates
(1)
Probability of how often a Non-Guaranteed Portfolio will experience income shortfalls and additional funds will have to be brought into the account to cover all income withdrawals and (2)
Probability of how often a Non-Guaranteed Portfolio will be sufficient to cover all income withdrawals.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "NG" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementNG",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "false",,
"lowest_income_distribution_flag": "false",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "true",,
"chart_data_flag": "false",,
"requestData": :[
{
"account_type": ":NG",,
"account_value": ":1000000",,
"income_withdrawal": ":65000",
"years_to_retirement": :5,,
"retirement_duration": :35,,
"underlying_fees": : 0.006,
"advisor_fees": : 0.01,,
"stock_percentage": : 0.35,
"bond_percentage": 0.65
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
no_income_shortfall |
Number |
Probability of how often a portfolio will be sufficient to cover all income withdrawals.
|
income_shortfall |
Number |
Probability of how often a portfolio will experience income shortfalls and additional funds will have to be brought into the account to cover all income withdrawals.
|
API RESPONSE BODY EXAMPLE
{
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"no_income_shortfall": 0.6160714285714286,
"income_shortfall": 0.3839285714285714,
}
]
}
DESCRIPTION
The Income Probabilities operation for Guaranteed Portfolio calculates
(1)
Probability of how often a Guaranteed Portfolio will experience income shortfalls and additional funds will have to be brought into the account to cover all income withdrawals and(2)
Probability of how often a Guaranteed Portfolio will be sufficient to cover all income withdrawals.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "G" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementNG",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "false",,
"lowest_income_distribution_flag": "false",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "true",,
"chart_data_flag": "false",,
"requestData": :[
{
"account_type": ":G",,
"account_value": ":1000000",,
"income_withdrawal": ":65000",
"years_to_retirement": :5,
"retirement_duration": :35,
"stock_percentage": : 0.8,
"bond_percentage": : 0.2,
"glwb_rider_fee": :0.0125,,
"sub_account_fund_fees" :0.006,
"m&e&a_fees": : 0.002,,
"advisor_fees": : 0.01,
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
no_income_shortfall |
Number |
Probability of how often a portfolio will be sufficient to cover all income withdrawals.
|
income_shortfall |
Number |
Probability of how often a portfolio will experience income shortfalls and additional funds will have to be brought into the account to cover all income withdrawals.
|
BODY EXAMPLE
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"no_income_shortfall": 1.0
"income_shortfall": 0.0
}
]
}
DESCRIPTION
The Income Probabilities operation for Combined Portfolio calculates:
(1)
Probability of how often a Combined Portfolio will experience income shortfalls and additional funds will have to be brought into the account to cover all income withdrawals and (2)
Probability of how often a Combined Portfolio will be sufficient to cover all income withdrawals.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "G" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementCombo",,
"no_income_shortfall_flag": "true",,
"income_shortfall_flag": "true",,
"highest_income_shortfall_flag": "false",,
"lowest_income_distribution_flag": "false",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "false",,
"chart_data_flag": "false",
"ng_and_g_common_parameters": :{
"years_to_retirement": "5",
"retirement_duration": "35",
}
"requestData": :[
{
"account_type": ":NG",
"account_value": ":300000",
"income_withdrawal": ":0",
"underlying_fees": :"0.006"
"advisor_fees": :"0.01",
"stock_percentage": : 1,
"bond_percentage": : 0,
},{
"account_type": "G",
"account_value": "700000",
"income_withdrawal": "45000",
"stock_percentage": "0.8",
"bond_percentage": "0.2",
"glwb_rider_fee": "0.0125",
"sub_account_fund_fees": "0.005",
"m&e&a_fees": "0.002",
"advisor_fees": "0.01"
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
no_income_shortfall |
Number |
Probability of how often a portfolio will be sufficient to cover all income withdrawals.
|
income_shortfall |
Number |
Probability of how often a portfolio will experience income shortfalls and additional funds will have to be brought into the account to cover all income withdrawals.
|
API RESPONSE BODY EXAMPLE
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"no_income_shortfall": 1.0
"income_shortfall": 0
}
]
}
DESCRIPTION
The Worst Case Income operation for Non-Guaranteed Portfolio calculates
(1)
Highest income shortfall for a Non-Guaranteed Portfolio and, correspondingly (2)
the lowest income distribution in that instance.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "NG" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementNG",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "false",,
"lowest_income_distribution_flag": "false",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "true",,
"chart_data_flag": "false",,
"requestData": :[
{
"account_type": ":NG",,
"account_value": ":1000000",,
"income_withdrawal": ":65000",
"years_to_retirement": :5,,
"retirement_duration": :35,,
"underlying_fees": : 0.006,
"advisor_fees": : 0.01,,
"stock_percentage": : 0.35,
"bond_percentage": 0.65
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
highest_income_shortfall |
Number |
The highest possible dollar amount that has to be brought in to cover all income withdrawals.
|
lowest_income_distribution |
Number |
The lowest possible dollar amount of income distributions from a portfolio without bringing in additional funds to cover all income withdrawals.
|
API RESPONSE BODY EXAMPLE
{
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"highest_income_shortfall": 711196.5685733315,
"lowest_income_distribution": 1038803.4314266685,
}
]
}
DESCRIPTION
The Worst Case Income operation for Guaranteed Portfolio calculates
(1)
Highest income shortfall for a Guaranteed Portfolio and, correspondingly (2)
the lowest income distribution in that instance.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "G" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementG",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "true",,
"lowest_income_distribution_flag": "true",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "false",,
"chart_data_flag": "false",,
"requestData": :[
{
"account_type": ":G",,
"account_value": ":1000000",,
"income_withdrawal": ":65000",
"years_to_retirement": :5,
"retirement_duration": :35,
"stock_percentage": : 0.8,
"bond_percentage": : 0.2,
"glwb_rider_fee": :0.0125,,
"sub_account_fund_fees" :0.006,
"m&e&a_fees": : 0.002,,
"advisor_fees": : 0.01,
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
highest_income_shortfall |
Number |
The highest possible dollar amount that has to be brought in to cover all income withdrawals.
|
lowest_income_distribution |
Number |
The lowest possible dollar amount of income distributions from a portfolio without bringing in additional funds to cover all income withdrawals.
|
API RESPONSE BODY EXAMPLE
{
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"highest_income_shortfall": 0.0,
"lowest_income_distribution": 2275000.0,
}
]
}
DESCRIPTION
The Worst Case Income operation for Combined Portfolio calculates
(1)
Highest income shortfall for a Combined Portfolio and, correspondingly, (2)
the lowest income distribution in that instance.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "NG" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementCombo",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "true",,
"lowest_income_distribution_flag": "true",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "false",,
"chart_data_flag": "false",
"ng_and_g_common_parameters": :{
"years_to_retirement": "5",
"retirement_duration": "35",
}
"requestData": :[
{
"account_type": ":NG",
"account_value": ":300000",
"income_withdrawal": ":0",
"underlying_fees": :"0.006"
"advisor_fees": :"0.01",
"stock_percentage": : 1,
"bond_percentage": : 0,
},{
"account_type": "G",
"account_value": "700000",
"income_withdrawal": "45000",
"stock_percentage": "0.8",
"bond_percentage": "0.2",
"glwb_rider_fee": "0.0125",
"sub_account_fund_fees": "0.005",
"m&e&a_fees": "0.002",
"advisor_fees": "0.01"
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
highest_income_shortfall |
Number |
The highest possible dollar amount that has to be brought in to cover all income withdrawals.
|
lowest_income_distribution |
Number |
The lowest possible dollar amount of income distributions from a portfolio without bringing in additional funds to cover all income withdrawals.
|
API RESPONSE BODY EXAMPLE
{
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"highest_income_shortfall": 0.0,
"lowest_income_distribution": 1575000.0,
}
]
}
DESCRIPTION
The Best Case Legacy operation for Non-Guaranteed Portfolio calculates
(1)
The highest possible residual value of the account after distribution of all income withdrawals.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "NG" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementNG",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "true",,
"lowest_income_distribution_flag": "true",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "false",,
"chart_data_flag": "false",,
"requestData": :[
{
"account_type": ":NG",,
"account_value": ":1000000",,
"income_withdrawal": ":50000",
"years_to_retirement": :0,
"retirement_duration": :35,
"stock_percentage": : 0.35,
"bond_percentage": : 0.65,
"underlying_fees": :0.006,
"advisor_fees": : 0.01,
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
highest_income_shortfall |
Number |
The highest possible residual value of the account after distribution of all income withdrawals.
|
API RESPONSE BODY EXAMPLE
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"highest_ending_account_value": 7812443.746099417
}
]
}
DESCRIPTION
The Best Case Legacy operation for Guaranteed Portfolio calculates
(1)
The highest possible residual value of the account after distribution of all income withdrawals.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "G" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementG",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "true",,
"lowest_income_distribution_flag": "true",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "false",,
"chart_data_flag": "false",,
"requestData": :[
{
"account_type": ":G",,
"account_value": ":1000000",,
"income_withdrawal": ":65000",
"years_to_retirement": :5,
"retirement_duration": :35,
"stock_percentage": : 0.8,
"bond_percentage": : 0.2,
"glwb_rider_fee": :0.0125,
"sub_account_fund_fees": 0.006,
"m&e&a_fees": 0.002,
"advisor_fees": : 0.01,
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
highest_ending_account_value |
Number |
The highest possible residual value of the account after distribution of all income withdrawals.
|
API RESPONSE BODY EXAMPLE
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"highest_ending_account_value": 1.183398255519225E7
}
]
}
DESCRIPTION
The Best Case Legacy operation for Combined Portfolio calculates
(1)
The highest possible residual value of the account after distribution of all income withdrawals.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
account_type |
String |
Indicator for whether account portfolio is Guaranteed or Guaranteed |
Must be "NG" |
years_to_retirement |
Integer |
Years to retirement of the account holder |
0 =< years_to_retirement =< 50 |
retirement_duration |
Integer |
Projected duration of years in retirement |
0 =< retirement_duration =< 50 |
account_value |
Number |
Amount of assets in the account today |
=< 0 |
income_withdrawal |
Number |
Desired annual income during retirement |
0 =< AND income_withdrawal / (account_value+1) =< 0.09 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 bond_percentagestock_percentage + bond_percentage + cash_percentage = 1 |
underlying_fees |
Number |
Underlying investment charges for investment vehicles |
>= 0underlying_fees AND stock_percentage + bond_percentage + cash_percentage = 1 |
advisor_fees |
Number |
Annual fees charged by the advisor on the account |
0 =<advisor_fees=< 0.05 underlying_fees + advisor_fees =< 0.05 |
no_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_income_shortfall_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
highest_ending_account_value_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
smart_irr_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
API REQUEST BODY EXAMPLE
{
"analyticService": "retirementService",
"requestDataList": [
{
"analyticService": "retirementService",,
"analyticServiceType": "retirementCombo",,
"no_income_shortfall_flag": "false",,
"income_shortfall_flag": "false",,
"highest_income_shortfall_flag": "true",,
"lowest_income_distribution_flag": "true",,
"highest_ending_account_value_flag": "false",,
"smart_irr_flag": "false",,
"chart_data_flag": "false",
"ng_and_g_common_parameters": :{
"years_to_retirement": "5",
"retirement_duration": "35",
}
"requestData": :[
{
"account_type": ":NG",
"account_value": ":300000",
"income_withdrawal": ":0",
"underlying_fees": :"0.006"
"advisor_fees": :"0.01",
"stock_percentage": : 1,
"bond_percentage": : 0,
},{
"account_type": "G",
"account_value": "700000",
"income_withdrawal": "45000",
"stock_percentage": "0.8",
"bond_percentage": "0.2",
"glwb_rider_fee": "0.0125",
"sub_account_fund_fees": "0.005",
"m&e&a_fees": "0.002",
"advisor_fees": "0.01"
}
]
}
]
}
API RESPONSE
API RESPONSE BODY SCHEMA
Field |
Type |
Description |
highest_ending_account_value |
Number |
The highest possible residual value of the account after distribution of all income withdrawals.
|
API RESPONSE BODY EXAMPLE
{
"statusCode": : 1,
"message": : "Success",
"result": : [
{
"highest_ending_account_value": 2.685562417569737E7
}
]
}
DESCRIPTION
The Required Investment operation calculates
(1)
The investment amount required today in a Guaranteed Portfolio to meet a guaranteed income need in the future.
BODY SCHEMA
Field |
Type |
Description |
Restraint |
current_age |
Integer |
Current age of portfolio owner |
0 =< current_age =<99 |
retirement_age |
Integer |
Projected retirement age of portfolio owner |
35 =< retirement_age =< 99 |
fund_expense_stock |
Number |
Fees for stock sub-account |
0 =< fund_expense_stock =< 0.05 |
fund_expense_cash |
Number |
Fees for cash sub-account |
0 =< fund_expense_cash =< 0.05 |
fund_expense_bond |
Number |
Fees for bond sub-account |
0 =< fund_expense_bond =< 0.05 |
bond_percentage |
Number |
Asset allocation to bonds |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
cash_percentage |
Number |
Asset allocation to cash |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
stock_percentage |
Number |
Asset allocation to stocks |
>= 0 AND stock_percentage + bond_percentage + cash_percentage = 1 |
core_contract_charge |
Number |
M&E&A Fees |
0 =< core_contract_charge =< 0.05 |
living_benefit_charge |
Number |
Fees for lifetime income guarantee |
Must be "true" or "false" |
income_shortfall_flag |
Script |
A flag indicates desired output in API response |
0 =< living_benefit_charge =< 0.05 |
income_gap |
Number |
Desired monthly guaranteed income at retirement age |
>= 0 |
lowest_income_distribution_flag |
Script |
A flag indicates desired output in API response |
Must be "true" or "false" |
stepups |
Script |
Indicator whether variable annuity offers step up or not for income base |
"Y" OR "N" |
withdrawal_rate |
Number |
Income guarantee rate for lifetime income benefit |
0 < withdrawal_rate =< 0.2 |
bonus_percentage |
Number |
Guaranteed rate to grow income base (also known as roll up rate) - if no bonus is offered, then input zero |
0 =< bonus_percentage =< 0.2 |
bonus_max_period |
Number |
Number of years bonus / roll up rate applies (resets at step up) |
>= 0 |
API REQUEST BODY EXAMPLE
{
"current_age": "50",
"retirement_age": "65",
"fund_expense_stock": "0.0082",
"fund_expense_cash": "0.0057",
"fund_expense_bond": "0.0089",
"bond_percentage": "0.2",
"cash_percentage": "0",
"stock_percentage": "0.8",
"core_contract_charge": "0.013",
"living_benefit_charge": "0.02",
"income_gap": "5000",
"stepups": "y",
"withdrawal_rate": "0.05",
"bonus_percentage": ".06",
"bonus_max_period": "10",
}
VAIT API RESPONSE
BODY SCHEMA
Field |
Type |
Description |
va_investment_amount |
Number |
Variable annuity investment required today based on historical market returns.
|
va_investment_amount_zero_market_return |
Number |
Variable annuity investment required today based on zero market returns.
|
API RESPONSE BODY EXAMPLE
{
"api_status": : Successful,
"api_message": : "",
"api_result": : {
"va_invest_amount": 556209.66,
"va_invest_amount_zero_market_return": 750000.00,
}
}