Hedgeness API reference

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 URLis 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 IDand a Client Secret which will be provided by Hedgeness during the Client registration process.

Access Token URL is the endpoint for authentication server:
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. SMARTstands 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

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
RESPONSE CODE/ STATUS: 200 / OK

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

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. SMARTstands 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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
CODE/ STATUS: 200 / OK

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

API RESPONSE 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. SMARTstands 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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
CODE/ STATUS: 200 / OK

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

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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
RESPONSE CODE/ STATUS: 200 / OK

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

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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
CODE/ STATUS: 200 / OK

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

API RESPONSE 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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
CODE/ STATUS: 200 / OK

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

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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
RESPONSE CODE/ STATUS: 200 / OK

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

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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
RESPONSE CODE/ STATUS: 200 / OK

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

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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
RESPONSE CODE/ STATUS: 200 / OK

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

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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
 https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
RESPONSE CODE/ STATUS: 200 / OK

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

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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
 https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
RESPONSE CODE/ STATUS: 200 / OK

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

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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/mgrail/v1/process/

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_percentage​stock_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

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
   
RESPONSE CODE/ STATUS: 200 / OK

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

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.

ENDPOINT

Endpoints
https://qa-analytics.hedgenessfin.com/vait/v1/process

API REQUEST

API REQUEST
   Post 
https://qa-analytics.hedgenessfin.com/vait/v1/process/

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

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

VAIT API RESPONSE
   
RESPONSE CODE/ STATUS: 200 / OK

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 REQUEST BODY EXAMPLE

{
"api_status": : Successful,
"api_message": : "",

"api_result": : {

"va_invest_amount": 556209.66,

"va_invest_amount_zero_market_return": 750000.00,
}
}
Solutions
Financial Advisors
Insurance Carriers​
Asset Managers
Company
Home
News
Team
About
​Privacy Policy
​
Contact Us
523 W Old Northwest Hwy
Suite 201
​Barrington, IL 60010
Terms of Use: Hedgeness Inc. is a software company and not authorized to sell any investment advice. The information contained herein may not be copied or redistributed; does not constitute investment advice offered by Hedgeness; is provided solely for informational purposes; does not constitute an offer to buy or sell a security; and is not warranted to be correct, complete or accurate. 

© 2022 HEDGENESS, INC. ALL RIGHTS RESERVED.