NAV

Nucleus  Proton  Electron

curl java javascript php python ruby

Introduction

Proton Base URL

https://api.hydrogenplatform.com/proton/v1

The Hydrogen Proton API is designed for added business logic on top of the core Nucleus data model within Hydrogen. Proton offers analytical tools, scoring, recommendations, and simulations.

Run in Postman

Authentication

All Hydrogen APIs use the same OAuth 2.0 authorization. Please refer to the Nucleus API for detailed documentation.

Client Credentials

If you are utilizing the Integration client libraries for client_credentials authorization, please view the sample code in the language of your choice in the right panel.

from __future__ import print_function
import time
import proton_api
from proton_api.rest import ApiException
from pprint import pprint

# Configure OAuth2 access token for authorization: oauth2
configuration = proton_api.Configuration()

# create an instance of the API class
api_instance = proton_api.AuthApi(proton_api.ApiClient(configuration))

api_token_response = api_instance.create_using_post_client_credentials("MYCLIENTID", "MYPASSWORD")
print(api_token_response.access_token)
configuration.access_token = api_token_response.access_token
require 'proton_api'
ProtonApi.configure do |config|
 config.create_client_credential("CLIENT_ID", "CLIENT_SECRET");
end
import com.hydrogen.proton.ApiException;
import com.hydrogen.proton.AuthApiClient;

# Create an instance of the Auth Api Client class
AuthApiClient authApiClient = new AuthApiClient();
try {
    authApiClient.createClientCredential("MYCLIENTID","MYCLIENTSECRET");
} catch (ApiException e) {
    e.printStackTrace();
}
var HydrogenProtonApi = require('hydrogen_proton_api');
var defaultClient = HydrogenProtonApi.ApiClient.instance;
# Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
# Create an instance of the Auth API class
var api = new HydrogenProtonApi.AuthApi();

# Callback function definition
var tokenGenerationCallback = function (error, data, response) {
    if (error) {
        console.error(error);
        process.exit(1);
    } else {
        console.log(response.request.method + ' : ' + response.request.url + '\n' + 'Output: ' + JSON.stringify(data, null, '\t') + '\n');
        oauth2.accessToken = data.access_token;
    }
};

# Token Generation for grant_type = client_credentials
api.createUsingPostClientCredentials({
    'grant_type': 'client_credentials',
    'client_id': 'MYCLIENTID',
    'client_secret': 'MYCLIENTSECRET'
}, tokenGenerationCallback);
use com\hydrogen\proton\ApiException;
use com\hydrogen\proton\AuthApiClient;

try {
    $config =
        AuthApiClient::getDefaultConfiguration()
            ->createClientCredential("MYCLIENTID", "MYCLIENTSECRET");
} catch (ApiException $e) {
    print_r($e);
}

Resource Owner Password Credentials

If you are utilizing the client libraries for password authorization, please view the sample code in the language of your choice in the right panel.

from __future__ import print_function
import time
import proton_api
from proton_api.rest import ApiException
from pprint import pprint

# Configure OAuth2 access token for authorization: oauth2
configuration = proton_api.Configuration()

# create an instance of the API class
api_instance = proton_api.AuthApi(proton_api.ApiClient(configuration))

# Fetch and set access token with client_id, client_secret, username, password
api_token_response = api_instance.api_instance.create_using_post_password_credentials("MYCLIENTID","MYCLIENTSECRET", "MYUSERNAME", "MYPASSWORD" )
print(api_token_response.access_token)
configuration.access_token = api_token_response.access_token
require 'proton_api'
ProtonApi.configure do |config|
 config.create_password_credential("CLIENT_ID", "CLIENT_SECRET", "USERNAME", "PASSWORD");
end
import com.hydrogen.proton.ApiException;
import com.hydrogen.proton.AuthApiClient;

# Create an instance of the Auth Api Client class
AuthApiClient authApiClient = new AuthApiClient();
try {
    authApiClient.createPasswordCredential("MYCLIENTID","MYCLIENTSECRET"
            ,"MYUSERNAME", "MYPASSWORD");
} catch (ApiException e) {
    e.printStackTrace();
}
var HydrogenProtonApi = require('hydrogen_proton_api');
var defaultClient = HydrogenProtonApi.ApiClient.instance;
# Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
# Create an instance of the Auth API class
var api = new HydrogenProtonApi.AuthApi();

# Callback function definition
var tokenGenerationCallback = function (error, data, response) {
    if (error) {
        console.error(error);
        process.exit(1);
    } else {
        console.log(response.request.method + ' : ' + response.request.url + '\n' + 'Output: ' + JSON.stringify(data, null, '\t') + '\n');
        oauth2.accessToken = data.access_token;
    }
};

# Token Generation for grant_type = password
api.createUsingPostPassword({
    'grant_type': 'password',
    'username' : 'MYUSERNAME',
    'password' : 'MYPASSWORD',
    'client_id': 'MYCLIENTID',
    'client_secret': 'MYCLIENTSECRET'
}, tokenGenerationCallback);
use com\hydrogen\proton\ApiException;
use com\hydrogen\proton\AuthApiClient;

try {
  $config =
        AuthApiClient::
        getDefaultConfiguration()->createPasswordCredential(
            "MYCLIENTID","MYCLIENTSECRET"
            ,"MYUSERNAME", "MYPASSWORD"
        );
} catch (ApiException $e) {
    print_r($e);
}

Fields

IDs

IDs are represented in universally unique identifier (UUID) format. A UUID is a string of 32 alphanumeric characters in the format 8-4-4-4-12. An example would be efa289b2-3565-42e6-850b-8dad25727e99. All requests that reference Nucleus data entities must utilize this UUID format.

DATES

Dates are represented in ISO-8601 format, as YYYY-MM-DD. An example would be 2018-01-10.

Errors

ERROR CODES

Code Description
400 Bad Request.
401 Unauthorized. Occurs when you are using an invalid or expired access token.
403 Forbidden. The request was valid but you are not authorized to access the resource.
404 Not Found. Occurs when you are requesting a resource which doesn’t exist such as an incorrect URL or incorrect ID.
429 Too Many Requests. Exceeded the rate limit set. Currently, there is no rate limit on the APIs.
500 Internal Server Error.
503 Service Unavailable. If the API is down for maintenance you will see this error.


STATUS CODES

Code Description
200 Ok. The request was successful.

Versioning

The Proton API is currently in major version 1.0. All features which are not backwards compatible will be pushed as a major version release. Features that we consider to be backwards compatible include the following:

Changelog

Changes and updated versions will be outlined here.

Date Change Description
2022-04-01 addition Added Card Authorization to allow tenants running their own debit programs to control authorization of transactions
2021-06-07 update Enabled support for household-level and business-level analytics to various services. Introduced a new transaction_status_scope parameter to improve analytics granularity for transaction-based services. Improved periodicity handling in Budget Calculator. Improved error handling for Cards services. Fixed various divide-by-zero errors. Fixed a bug in Cash Flow Analysis that led to incorrect transactions being included in the analysis for certain requests.
2021-06-07 addition Added the Spending Analysis service to the Personal Financial Management module. Added the Card Analysis service to the Cards module.
2020-12-31 addition Added Card Limit Check. Added support for currency_conversion across various services. Added functionality to Budget Calculator to calculate average historical spending across budget categories. Added an only_cleansed parameter to services that consume Portfolio Transactions. Standardized the handling of boolean input parameters to minimize ambiguity.
2020-03-04 update Enhanced error messaging for Goal Accumulation Allocation when underlying security price data is insufficient. Added more descriptive error messaging when a Proton request fails due to an issue with another Hydrogen product such as Nucleus API or Integration API. Improved input validation on the opt_config object and more descriptive error messaging when passing it empty strings as tickers for the following endpoints: Goal Accumulation Allocation, Goal Decumulation Allocation. Updates to Budget Calculator: Changed as_of_date to use UTC instead of the local current date. Relaxed constraints on underlying data by treating a lack of valid transaction records for a budget as 0 spending. Enhanced results for a budget with a null subcategory so that it will consider all transactions that map at the category level. Improved error handling when passing an invalid budget_id.
2020-02-14 update Made initial_balance parameter optional with a default value of 0 for the following endpoints: Education Calculator, Savings Calculator. Nucleus entity connected to Goal Accumulation Allocation and Goal Decumulation Allocation endpoints. Improved error messaging for Goals when sourcing data from Nucleus, and for Goal Decumulation when there is an invalid periodicity relationship between withdrawal_config amounts and the goal horizon. Adjusted Life Insurance Needs Calculator to allow optional inputs to have their default values properly set. Changed Goal Accumulation services to prevent certain nested inputs in the recommendation_config field from being required and to properly process deposit_config period references for certain combinations of deposit frequency and goal horizon frequency. Changed Goal Decumulation services to produce the proper error message when d_horizon has a value of 0 and to allow for successful analysis in some cases when a_horizon has a value of 0.
2019-12-19 update Nucleus data entities connected to Goals and Financial Planning.
2019-08-22 update Fixed a series of bugs: Enabled Financial Health Check to properly handle cases where the ratio denominator is 0. Updated Education Calculator & Retirement Calculator to prevent excess cash to be left in deposit_schedule at the end of the time horizon when an inflation rate was applied.
2019-08-22 update Updated Emergency Fund Calculator to remove a restriction from the interest_rate parameter. Updated Savings Calculator to remove the constraint on the length of the return_schedule array.
2019-08-22 addition Added two new services to the Personal Financial Management module: Budget Calculator, Cash Flow Analysis.
2019-03-26 update Fixed a bug in which the impact of inflation was reflected inconsistently across Financial Planning calculators. Fixed a bug in which the arithmetic mean return was used instead of the geometric mean in Goals allocation services.
2019-03-26 update Introduced two new parameters to all services in the Goals module, adjust_for_compounding and compounding_rate, which help to approximate a compounding effect on deposits for specific request configurations.
2019-01-24 update Fixed a bug in the Goals module in which portfolio risk was improperly calculated when converting between certain time frequencies. Added handling for Mortgage Calculator cases in which down_payment could be negative.
2018-12-07 addition Added the Financial Health Check service to the Financial Health module, which offers the ability to assess an individual’s status through a series of financial ratios.
2018-08-08 update Enhanced all services in the Goals module, making the framework more robust by allowing for greater levels of customization and the ability to handle a wider array of goal configurations.
2018-07-02 addition Added a suite of financial calculators, including Education, Mortgage, Life Insurance Needs, Major Purchase, Retirement, and Savings.

Wallet

These services perform business logic and analysis on the Hydrogen Wallet product.

Card Analysis

Card Analysis provides a top-down view of card spending activity. Data may be analyzed at the client, business, card program, or tenant level. The analysis gives insight into top spenders, top cards, metrics such as average transaction size, and a historical view to see how card activity changes over time.

HTTP REQUEST

POST /card_analysis

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "card_program_id": "48f67eea-0ae6-4396-add7-65f57c515367",
        "currency_code": "USD",
        "start_date": "2021-03-01",
        "end_date": "2021-05-11",
        "card_status_scope": [
            "activated"
        ],
        "transaction_status_scope": [
            "completed",
            "pending"
        ],
        "response_limit": 1,
        "history_frequency_interval": "month",
        "show_history": true,
        "show_top_cardholders": true,
        "show_top_cards": true
      }' "https://api.hydrogenplatform.com/proton/v1/card_analysis"
CardsApi cardsApi = new CardsApi();
        CardAnalysisRequest analysisRequest = new CardAnalysisRequest();
        analysisRequest.setTransactionStatusScope(Arrays.asList("completed",
                "pending"));
        analysisRequest.setCardProgramId(UUID.fromString("4ef87de7-86f5-42fb-819b-abb1d0d94cdb"));
        analysisRequest.setCurrencyCode("USD");
        analysisRequest.setStartDate(LocalDate.parse("2021-03-01"));
        analysisRequest.setEndDate(LocalDate.parse("2021-05-11"));
        analysisRequest.setCardStatusScope(Arrays.<String>asList("activated"));
        analysisRequest.setResponseLimit(1);
        analysisRequest.setHistoryFrequencyInterval(MONTH);
        analysisRequest.setShowHistory(TRUE);
        analysisRequest.setShowTopCardholders(TRUE);
        analysisRequest.setShowTopCards(TRUE);
        analysisRequest.setCurrencyConversion("USD");
        Map<String, Object> cardAnalysisResponse = cardsApi.cardAnalysis(analysisRequest);
        System.out.println(cardAnalysisResponse);
api_instance = proton_api.CardsApi(proton_api.ApiClient(configuration))
card_analysis_request = proton_api.CardAnalysisRequest(
    transaction_status_scope=["completed", "pending"], card_program_id="4ef87de7-86f5-42fb-819b-abb1d0d94cdb",
    currency_code="USD", start_date="2021-03-01", end_date="2021-05-11", card_status_scope=["activated"],
    response_limit=1, history_frequency_interval='month', show_history=True, show_top_cardholders=True,
    show_top_cards=True, currency_conversion='USD'
)
try:
    # Card - Card Analysis
    api_response = api_instance.card_analysis(card_analysis_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling CardsApi->card_analysis: %s\n" % e)
api_instance = ProtonApi::CardsApi.new
cardAnalysisRequest = ProtonApi::CardAnalysisRequest.new
begin
  cardAnalysisRequest.client_id = "dbad7769-5b53-4e8a-87db-5c83bf65ced4"
  cardAnalysisRequest.currency_code="USD"
  cardAnalysisRequest.start_date = "2021-01-01"
  cardAnalysisRequest.end_date ="2021-05-17"
  cardAnalysisRequest.response_limit=3
  cardAnalysisRequest.transaction_status_scope = ["completed", "pending"]
  cardAnalysisRequest.card_status_scope = ["activated"]
  cardAnalysisRequest.show_history = true
  cardAnalysisRequest.history_frequency_interval = "month"
  cardAnalysisRequest.response_limit = 1
  cardAnalysisRequest.show_top_cardholders = true
  cardAnalysisRequest.show_history = true
  cardAnalysisRequest.show_top_cards = true
  cardLimitResponse = api_instance.card_analysis(cardAnalysisRequest)
  p cardLimitResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling card_Analysis_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\CardsApi(
    new GuzzleHttp\Client(),
    $config
);
$card_analysis_req = new \com\hydrogen\proton\Model\CardAnalysisRequest();
try {
    $card_analysis_req->setCardProgramId("6f0aa30e-1749-49dd-97f8-b07d7917abd8");
    $card_analysis_req->setCurrencyCode("USD");
    $card_analysis_req->setCurrencyConversion("USD");
    $card_analysis_req->setStartDate( "2021-01-01");
    $card_analysis_req->setEndDate("2021-03-17");
    $card_analysis_req->setResponseLimit(3);
    $card_analysis_req->setHistoryFrequencyInterval("month");
    $card_analysis_req->setTransactionStatusScope(["completed",
        "pending"]);
    $card_analysis_req->setCardStatusScope(["activated"]);
    $card_analysis_req->setShowHistory(true);;
    $card_analysis_req->setShowTopCardholders(true);
    $card_analysis_req->setShowTopCards(true);
    $cardanalysisresponse = $apiInstance->cardAnalysis($card_analysis_req);
    print_r($cardanalysisresponse);
} catch (Exception $e) {
    echo 'Exception when calling CardsApi->cardAnalysis: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.CardsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
    var api = new HydrogenProtonApi.CardsApi();
    var cardAnalysisRequest = new HydrogenProtonApi.CardAnalysisRequest();
    cardAnalysisRequest.cardProgramId = "6f0aa30e-1749-49dd-97f8-b07d7917abd8";
    cardAnalysisRequest.currency_code = "USD";
    cardAnalysisRequest.start_date = "2021-03-01";
    cardAnalysisRequest.end_date = "2021-05-17";
    cardAnalysisRequest.card_status_scope = ["activated"]
    cardAnalysisRequest.response_limit = 1
    cardAnalysisRequest.history_frequency_interval = "month";
    cardAnalysisRequest.card_status_scope = null;
    cardAnalysisRequest.transaction_status_scope = [
        "completed",
        "pending"
    ];
    cardAnalysisRequest.show_history = true;
    cardAnalysisRequest.show_top_cardholders = true;
    cardAnalysisRequest.show_top_cards = true;
    api.cardAnalysis(cardAnalysisRequest, callback);

ARGUMENTS

Parameter Description
client_id
UUID
The ID of a Nucleus Client to analyze. If provided, all cards linked to this client will be considered. If one of client_id, business_id or card_program_id is not passed, all clients within the tenant will be considered.
business_id
UUID
The ID of a Nucleus Business to analyze. If provided, all clients linked to this business will be considered. If one of client_id, business_id or card_program_id is not passed, all clients within the tenant will be considered.
card_program_id
UUID
The ID of a Nucleus Card Program to analyze. If provided, all clients linked to this card program will be considered. If one of client_id, business_id or card_program_id is not passed, all clients within the tenant will be considered.
currency_code
string
The alphabetic currency code used to conduct the analysis, limited to 3 characters. Only records with this currency code will be considered. Defaults to USD if currency_conversion is not provided. If currency_conversion is provided, all origin currencies will be considered by default. See Currencies.
currency_conversion
string
The alphabetic currency code used to conduct the analysis, limited to 3 characters. Records will be converted from their original currency to the one indicated here. Conversions are supported both to and from the following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See Currencies.
start_date
date
Start date of the analysis period. Defaults to the earliest date of available cardholder spending data.
end_date
date
End date of the analysis period. Defaults to today’s date.
card_status_scope
array[string]
If populated, only Nucleus Cards whose status matches one of the array values are considered in the analysis. Defaults to null, meaning transaction data from all cards are considered regardless of the status.
transaction_status_scope
array[string]
If populated, only Nucleus Portfolio Transactions whose status matches one of the array values are considered in the analysis. Defaults to null, meaning all transactions are considered regardless of the status.
response_limit
integer
Maximum number of records to be returned in top_businesses, top_cardholders, and top_cards. Defaults to 10.
history_frequency_interval
string
The frequency of historical cardholder spending data. Value may be day, week, month, quarter, or year. Defaults to month.
show_history
boolean
If true, returns a history of spending, in total, by business, by cardholder, and by card. Defaults to false.
show_top_cardholders
boolean
If true, returns details on the top spending cardholders. Defaults to false.
show_top_cards
boolean
If true, returns details on the top spending cards. Defaults to false.

Example Response

{
    "currency_code": "USD",
    "analysis_start": "2021-03-01",
    "analysis_end": "2021-05-11",
    "summary": {
        "number_of_cardholders": 5,
        "number_of_cards": 5,
        "total_amount_spent": 1925.0,
        "number_of_transactions": 6,
        "mean_transaction_amount": 320.83,
        "history": [
            {
                "period_start": "2021-03-01",
                "period_end": "2021-03-31",
                "amount_spent": 125.0
            },
            {
                "period_start": "2021-04-01",
                "period_end": "2021-04-30",
                "amount_spent": 1800.0
            },
            {
                "period_start": "2021-05-01",
                "period_end": "2021-05-11",
                "amount_spent": 0.0
            }
        ]
    },
    "top_cardholders": [
        {
            "name": "Crystal Jennings",
            "number_of_cards": 1,
            "total_amount_spent": 750.0,
            "number_of_transactions": 1,
            "mean_transaction_amount": 750.0,
            "history": [
                {
                    "period_start": "2021-03-01",
                    "period_end": "2021-03-31",
                    "amount_spent": 0.0
                },
                {
                    "period_start": "2021-04-01",
                    "period_end": "2021-04-30",
                    "amount_spent": 750.0
                },
                {
                    "period_start": "2021-05-01",
                    "period_end": "2021-05-11",
                    "amount_spent": 0.0
                }
            ]
        }
    ],
    "top_cards": [
        {
            "card_holder_name": "Crystal A Jennings",
            "institution_name": "Hydro Bank",
            "card_name": "Select Debit Card",
            "total_amount_spent": 750.0,
            "number_of_transactions": 1,
            "mean_transaction_amount": 750.0,
            "history": [
                {
                    "period_start": "2021-03-01",
                    "period_end": "2021-03-31",
                    "amount_spent": 0.0
                },
                {
                    "period_start": "2021-04-01",
                    "period_end": "2021-04-30",
                    "amount_spent": 750.0
                },
                {
                    "period_start": "2021-05-01",
                    "period_end": "2021-05-11",
                    "amount_spent": 0.0
                }
            ]
        }
    ]
}

RESPONSE

Field Description
currency_code Currency code associated with monetary response values.
analysis_start Start date of the analysis period. If start_date was provided in the request, it is reflected here. If start_date was not provided, this value is derived dynamically.
analysis_end End date of the analysis period. If end_date was provided in the request, it is reflected here. If end_date was not provided, this value is derived dynamically.
summary High-level analysis of card spending.
      number_of_cardholders Number of cardholders, or Nucleus Clients with cards.
      number_of_cards Number of Nucleus Cards.
      total_amount_spent Total amount spent over the analysis period.
      number_of_transactions Number of card transactions, or Nucleus Portfolio Transactions linked to a card.
      mean_transaction_amount Average card transaction amount over the analysis period.
      history Historical total card spending data, with frequency dependent on the history_frequency_interval value passed in the request. Each entry has the fields shown below.
            period_start Period start date.
            period_end Period end date.
            amount_spent Amount spent in the period.
top_cardholders Cardholders that spent the most over the analysis period. Each entry represents a single cardholder and has the fields shown below.
      name Name of the cardholder associated with the spending.
      number_of_cards Number of cards held by the cardholder.
      total_amount_spent Total amount spent over the analysis period.
      number_of_transactions Number of card transactions.
      mean_transaction_amount Average card transaction amount over the analysis period.
      history Historical cardholder spending data, with frequency dependent on the history_frequency_interval value passed in the request. Each entry has the fields shown below.
            period_start Period start date.
            period_end Period end date.
            amount_spent Amount spent in the period.
top_cards Cards that spent the most over the analysis period. Each entry represents a single card and has the fields shown below.
      card_holder_name Name of the cardholder that appears on the card.
      institution_name Name of the institution that issued the card.
      card_name Name of the card associated with the spending.
      total_amount_spent Total amount spent over the analysis period.
      number_of_transactions Number of card transactions.
      mean_transaction_amount Average card transaction amount over the analysis period.
      history Historical card spending data, with frequency dependent on the history_frequency_interval value passed in the request. Each entry has the fields shown below.
            period_start Period start date.
            period_end Period end date.
            amount_spent Amount spent in the period.

NUCLEUS DATA DEPENDENCIES

Deposit

There are no API services required to perform business logic and analysis on the Hydrogen Deposit product. All necessary operations are performed in the Nucleus data model and our no-code apps.

Reward

There are no API services required to perform business logic and analysis on the Hydrogen Reward product. All necessary operations are performed purely no-code through the Hydrogen Account Portal.

Spend

These services perform business logic and analysis on the Hydrogen Spend product.

Card Authorization

Card Authorization provides the ability to authorize a card transaction based on a variety of pre-defined spending controls. For spending control authorizations, information about the transaction, such as transaction type, transaction category, merchant, and location is consumed by the service. This information, along with the client’s card transaction history, is compared to existing spending and transaction limits. If the limits have not been or will not be exceeded by the transaction, it will be authorized. Cleansing of raw transaction data, utilization of audit logs, and full and partial authorizations of the requested amount are supported.

HTTP REQUEST

POST /card_authorization

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "card_id": "3f2a4530-a0f5-4eca-a7b1-c151b1175f99",
        "currency_code": "USD",
        "auth_type": [
            "spending_control"
        ],
        "amount": 300,
        "date": "2020-11-20T08:00:00.000+0000",
        "transaction_type": "purchase",
        "merchant_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
        "merchant": "Delta",
        "merchant_category_code": 2345,
        "mid": "123456790",
        "transaction_category_id": "48f67eea-0ae6-4396-add7-65f57c515367",
        "transaction_category": "Travel",
        "description": "DELTA AIRLINES #235920",
        "memo":  null,
        "location": {
            "country": "US"
        },
        "partial_auth": false,
        "cleanse_data": false,
        "use_audit_log": false
      }' "https://api.hydrogenplatform.com/proton/v1/card_authorization"
CardsApi cardsApi = new CardsApi();
        CardTransactionAuthorizationRequest cardTransactionAuthorizationRequest =
                new CardTransactionAuthorizationRequest();
        cardTransactionAuthorizationRequest.setCardId(
                UUID.fromString("72c626af-8490-4f95-8bba-be4eb325215b")
        );
        cardTransactionAuthorizationRequest.setCurrencyCode("USD");
        cardTransactionAuthorizationRequest.setAuthType(Arrays.<CardTransactionAuthorizationRequest.AuthTypeEnum>asList(
                SPENDING_CONTROL
        ));
        cardTransactionAuthorizationRequest.setAmount(300F);
        cardTransactionAuthorizationRequest.setTransactionType(PURCHASE);
        cardTransactionAuthorizationRequest.setDate(OffsetDateTime.of(
                2020, 11, 20, 00, 00, 00, 00, ZoneOffset.UTC
        ));
        cardTransactionAuthorizationRequest.setMerchantId(
                UUID.fromString("fffe7fd8-39a5-4868-8095-b061c415dc2f")
        );
        cardTransactionAuthorizationRequest.setMerchantCategoryCode(2345);
        cardTransactionAuthorizationRequest.setMerchant("Delta");
        cardTransactionAuthorizationRequest.setMid("123456790");
        cardTransactionAuthorizationRequest.setTransactionCategoryId(
                UUID.fromString("a9bbdabf-afae-420e-9990-c5b37eb0fc28")
        );
        cardTransactionAuthorizationRequest.setTransactionCategory("Travel");
        cardTransactionAuthorizationRequest.setDescription("DELTA AIRLINES #235920");
        Location location =  new Location();
        location.setCountry("US");
        cardTransactionAuthorizationRequest.setLocation(location);
        cardTransactionAuthorizationRequest.setPartialAuth(FALSE);
        cardTransactionAuthorizationRequest.setCleanseData(FALSE);
        cardTransactionAuthorizationRequest.setUseAuditLog(FALSE);
        Map<String, Object> cardTransactionAuthorization = cardsApi
                .cardTransactionAuthorization(cardTransactionAuthorizationRequest);
        System.out.println(cardTransactionAuthorization);
api_instance = proton_api.CardsApi(proton_api.ApiClient(configuration))
#      Card Transaction Authorization Request
card_transaction_authorization_request = proton_api.CardTransactionAuthorizationRequest(
    card_id="72c626af-8490-4f95-8bba-be4eb325215b", currency_code="USD", auth_type=['spending_control'],
    amount=300, transaction_type='purchase', _date="2020-11-20T08:00:00.000+0000", merchant_id="fffe7fd8-39a5-4868-8095-b061c415dc2f",
    merchant_category_code=2354, merchant='Delta', mid='12345', transaction_category_id="a9bbdabf-afae-420e-9990-c5b37eb0fc28",
    transaction_category='Travel', description="DELTA AIRLINES #235920", location=proton_api.Location(country="US"),
    partial_auth=False, cleanse_data=False, use_audit_log=False
)
try:
    # Card - Card Transaction Authorization
    api_response = api_instance.card_transaction_authorization(card_transaction_authorization_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling CardsApi->card_transaction_authorization: %s\n" % e)
api_instance = ProtonApi::CardsApi.new
card_authorization_request= ProtonApi::CardTransactionAuthorizationRequest.new

begin
  card_authorization_request.card_id="72c626af-8490-4f95-8bba-be4eb325215b"
  card_authorization_request.amount=300
  card_authorization_request.currency_code="USD"
  card_authorization_request.transaction_type ="purchase"
  card_authorization_request.date ="2016-01-07"
  card_authorization_request.merchant="Delta"
  card_authorization_request.merchant_category=null
  card_authorization_request.merchant_category_code= 2345
  card_authorization_request.merchant_id = "fffe7fd8-39a5-4868-8095-b061c415dc2f"
  card_authorization_request.mid = 123456790
  card_authorization_request.transaction_category_id = "a9bbdabf-afae-420e-9990-c5b37eb0fc28"
  card_authorization_request.transaction_category = "travel"
  card_authorization_request.description="DELTA AIRLINES #235920"
  location = ProtonApi::Location.new
  location.country = "US"
  card_authorization_request.location = location
  card_authorization_request.auth_type=["spending_control"]
  card_authorization_request.partial_auth=false
  card_authorization_request.cleanse_data=false
  card_authorization_request.use_audit_log = false

  cardauthorizationresponse = api_instance.card_authorization(card_authorization_request)
  p cardauthorizationresponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling card_authorization_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\CardsApi(
    new GuzzleHttp\Client(),
    $config
);
$cardAuthorizationRequest = new com\hydrogen\proton\Model\CardTransactionAuthorizationRequest();
try {
    $cardAuthorizationRequest->setcardid("72c626af-8490-4f95-8bba-be4eb325215b");
    $cardAuthorizationRequest->setamount(300);
    $cardAuthorizationRequest->setcurrencycode("USD");
    $cardAuthorizationRequest->settransactiontype("purchase");
    $cardAuthorizationRequest->setdate("2020-11-20T08:00:00.000+0000");
    $cardAuthorizationRequest->setmerchant("Delta");
    $cardAuthorizationRequest->setMid('123456790');
    $cardAuthorizationRequest->setMerchantId("fffe7fd8-39a5-4868-8095-b061c415dc2f");
    $cardAuthorizationRequest->setmerchantcategorycode(2345);
    $cardAuthorizationRequest->setdescription(null);
    $cardAuthorizationRequest->setauthtype(array("spending_control"));
    $cardAuthorizationRequest->setTransactionCategoryId("a9bbdabf-afae-420e-9990-c5b37eb0fc28");
    $cardAuthorizationRequest->setTransactionCategory("Travel");
    $cardAuthorizationRequest->setDescription("DELTA AIRLINES #235920");
    $location  = new \com\hydrogen\proton\Model\Location();
    $location->setCountry("US");
    $cardAuthorizationRequest->setLocation($location);
    $cardAuthorizationRequest->setpartialauth(false);
    $cardAuthorizationRequest->setUseAuditLog(false);
    $cardAuthorizationRequest->setcleansedata(false);
    $cardAuthorizationResponse = $apiInstance->cardTransactionAuthorization($cardAuthorizationRequest);
    print_r($cardAuthorizationResponse);
} catch (Exception $e) {
    echo 'Exception when calling CardsAPI->cardAuthorization: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.CardsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.CardsApi();
    var cardauthorizationRequest= new HydrogenProtonApi.CardTransactionAuthorizationRequest();
    var location = new HydrogenProtonApi.Location();
    cardauthorizationRequest.card_id= "9c2d898f-58a0-4701-9d53-e7c5d2b8831e";
    cardauthorizationRequest.amount=300;
    cardauthorizationRequest.currency_code="USD",
        cardauthorizationRequest.transaction_type= "purchase",
        cardauthorizationRequest.date= "2021-06-03T18:24:04.186+0000";
    cardauthorizationRequest.merchant= "Delta";
    cardauthorizationRequest.merchantId = "fffe7fd8-39a5-4868-8095-b061c415dc2f";
    cardauthorizationRequest.mid = "123456790";
    cardauthorizationRequest.transactionCategoryId = "a9bbdabf-afae-420e-9990-c5b37eb0fc28";
    cardauthorizationRequest.transactionCategory = "Travel";
    cardauthorizationRequest.merchant_category=null;
    cardauthorizationRequest.merchant_category_code= 2345;
    cardauthorizationRequest.description="DELTA AIRLINES #235920";
    cardauthorizationRequest.auth_type=["spending_control"];
    location.country = "US";
    cardauthorizationRequest.location = location;
    cardauthorizationRequest.partial_auth=true;
    cardauthorizationRequest.cleanse_data=false;
    cardauthorizationRequest.useAuditLog =false;
    api.cardTransactionAuthorization(cardauthorizationRequest, callback)

ARGUMENTS

Parameter Description
card_id
UUID, required
The ID of a Nucleus Card that the transaction corresponds to.
currency_code
string, required
The alphabetic currency code of the transaction, limited to 3 characters. Only records with this currency code will be considered. See Currencies.
auth_type
array[string], required
The type of authorization to be performed on the transaction. Value may be spending_control. If spending_control is passed, the transaction will be authorized if it does not exceed any of the existing Nucleus Spending Controls.
amount
float, required
Amount of the transaction to be authorized. A negative value indicates a debit, while a positive value indicates a credit.
date
timestamp, required
Date and time of the transaction to be authorized.
transaction_type
string, required
Type of the transaction to be authorized. Value may be purchase, atm_withdrawal, or other.
transaction_category
string
Name of the category of the transaction to be authorized. See Transaction Categories.
transaction_category_id
UUID
ID of the category of the transaction to be authorized. See Transaction Categories.
merchant
string
Name of the merchant of the transaction to be authorized. See Merchants.
merchant_id
UUID
ID of the merchant of the transaction to be authorized. See Merchants.
mid
string
Internal merchant ID of the transaction to be authorized.
merchant_category_code
string
Merchant category code of the transaction to be authorized.
description
string
Description of the transaction to be authorized.
memo
string
Memo of the transaction to be authorized.
location
object
Location details of the transaction to be authorized.
      country
      string
ISO 3166 ALPHA-2 country code of the transaction to be authorized. See Countries.
partial_auth
boolean
If true, a portion of the transaction amount may be authorized. Defaults to false, meaning only the full transaction amount may be authorized.
cleanse_data
boolean
If true, some of the transaction data provided in this request will be submitted for data cleansing prior to any analysis. This data may include merchant, merchant_category_code, description, memo, and amount. Defaults to false, meaning that no additional data cleansing will be performed on the transaction data provided. This service requires access to the plasma premium offering.
use_audit_log
boolean
If true, the most recent Audit Log created by Card Limit Check will be utilized to derive the current status of any spending controls. Defaults to false, meaning that the status of any spending controls will be derived dynamically in this analysis.

Example Response

{
    "is_authorized": true,
    "requested_amount": 1300.0,
    "authorized_amount": 1000.0,
    "rejected_amount": 300.0,
    "rejection_details": {
        "message": "atm_withdrawal_spending_limit",
        "spending_control_id": "5d6e3328-09f4-4450-bb56-2ab9751fc0d7",
        "control_type": "spending_limit",
        "control_scope": "atm_withdrawal",
        "control_value": null,
        "frequency_unit": "one_time",
        "frequency": 1,
        "limit_value": 1000.0,
        "limit_used": 0,
        "limit_remaining": 1000.0
    }
}

RESPONSE

Field Description
is_authorized Indicates whether the transaction was successfully authorized. A value of true indicates that the transaction was fully or partially authorized, while a value of false indicates that the transaction was rejected.
requested_amount Amount requested to be authorized.
authorized_amount Amount authorized.
rejected_amount Amount rejected.
rejection_details Details of the rejection when all or a portion of the requested amount is rejected.
      message Message explaining the reason for the rejection. Value will be one of the following: all_spending_limit, purchase_spending_limit, atm_withdrawal_spending_limit,transaction_category_spending_limit, transaction_category_id_spending_limit, merchant_spending_limit, merchant_id_spending_limit, location_spending_limit, all_transaction_limit, purchase_transaction_limit, atm_withdrawal_transaction_limit, transaction_category_transaction_limit, transaction_category_id_transaction_limit, merchant_transaction_limit, merchant_id_transaction_limit, location_transaction_limit, transaction_category_allow_list, transaction_category_id_allow_list, merchant_allow_list, merchant_id_allow_list, location_allow_list, transaction_category_deny_list, transaction_category_id_deny_list, merchant_deny_list, merchant_id_deny_list, location_deny_list, mid_restriction,time_delay_restriction.
      spending_control_id ID of the Nucleus Spending Control that triggered the rejection.
      control_type Type of the spending control. Value may be spending_limit, transaction_limit, allow_list, or deny_list.
      control_scope Scope of the spending control. Value may be all, purchase, atm_withdrawal, or merchant_category.
      control_value Specific value that triggered the rejection. Will be one of the control_values from the corresponding spending control.
      frequency_unit Frequency unit of the spending control. Value may be one_time, daily, weekly, monthly, quarterly, or annually.
      frequency Frequency of the spending control. Indicates the number of frequency_unit between each period.
      limit_value Value of the spending control limit.
      limit_used Value already used towards this spending control limit.
      limit_remaining Value that remains to be used towards this spending control limit.
existing_balance Card balance prior to the processing of any newly authorized transaction.
new_balance Card balance after the processing of any newly authorized transaction.

NUCLEUS DATA DEPENDENCIES

Card Limit Check

Card Limit Check makes it easy to monitor usage of a client’s cards relative to their set limits. This service analyzes a client’s spending and transaction limits against their card transaction history for the specified period. A detailed status of each individual limit is returned, indicating how much of the limit has been used or is remaining, whether or not the limit has been breached, and how much time is left in the period before the limit resets.

HTTP REQUEST

POST /card_limit_check

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "159bb162-b911-4c97-ba96-53493e62674d",
        "currency_code": "USD",
        "as_of_date": "2020-12-15T00:00:00.000+0000",
        "create_log": false
      }' "https://api.hydrogenplatform.com/proton/v1/card_limit_check"
CardsApi cardsApi = new CardsApi();
        CardLimitCheckRequest cardLimitCheckRequest = new CardLimitCheckRequest();
        cardLimitCheckRequest.setClientId(UUID.fromString("ed8efaa5-4a3f-4f01-888c-539cf177cb6a"));
        cardLimitCheckRequest.setCreateLog(FALSE);
        cardLimitCheckRequest.setCurrencyCode("USD");
        cardLimitCheckRequest.setAsOfDate(OffsetDateTime.of(
                2020, 11, 20, 00, 00, 00, 00, ZoneOffset.UTC
        ));
        Map<String, Object> cardLimitCheckResponse = cardsApi.cardLimitCheck(cardLimitCheckRequest);
        System.out.println(cardLimitCheckResponse);
api_instance = proton_api.CardsApi(proton_api.ApiClient(configuration))
card_limit_check_request = proton_api.CardLimitCheckRequest(
    client_id="ed8efaa5-4a3f-4f01-888c-539cf177cb6a", create_log=False,
    currency_code="USD", as_of_date="2020-11-20T08:00:00.000+0000"
)
try:
    # Card - Card Limit Check
    api_response = api_instance.card_limit_check(card_limit_check_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling CardsApi->card_limit_check: %s\n" % e)
api_instance = ProtonApi::CardsApi.new
card_limit_check_request= ProtonApi::CardLimitCheckRequest.new

begin
  card_limit_check_request.client_id="ed8efaa5-4a3f-4f01-888c-539cf177cb6a"
  card_limit_check_request.currency_code="USD"
  card_limit_check_request.create_log = false
  card_limit_check_request.as_of_date = "2020-10-10"
  cardLimitResponse = api_instance.card_limit_check(card_limit_check_request)
  p cardLimitResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling card_limit_check_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\CardsApi(
    new GuzzleHttp\Client(),
    $config
);
$cardLimitCheckRequest = new com\hydrogen\proton\Model\CardLimitCheckRequest();
try {
    $cardLimitCheckRequest->setclientid("ed8efaa5-4a3f-4f01-888c-539cf177cb6a");
    $cardLimitCheckRequest->setcurrencycode("USD");
    $cardLimitCheckRequest->setAsOfDate("2020-11-20T08:00:00.000+0000");
    $cardLimitCheckRequest->setCreateLog(false);
    $cardLimitResponse = $apiInstance->cardLimitCheck($cardLimitCheckRequest);
    print_r($cardLimitResponse);
} catch (Exception $e) {
    echo 'Exception when calling CardsApi->cardLimitCheck: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.CardsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.CardsApi();
var cardlimitcheckRequest= new HydrogenProtonApi.CardLimitCheckRequest();
    cardlimitcheckRequest.client_id = "b2e59b04-63a3-4fa8-b777-7450974c5378";
    cardlimitcheckRequest.createLog = "false";
    cardlimitcheckRequest.asOfDate = "2020-10-10";
    cardlimitcheckRequest.currency_code="USD";
        api.cardLimitCheck(cardlimitcheckRequest, callback);

ARGUMENTS

Parameter Description
client_id
UUID, required
The ID of a Nucleus Client for whom to conduct the analysis.
currency_code
string, required
The alphabetic currency code used to conduct the analysis, limited to 3 characters. Only records with this currency code will be considered. See Currencies.
as_of_date
datetime
The date and time as of which to conduct the analysis. Defaults to the current date and time.
create_log
boolean
If true, a record of this Proton request URL, request body, response body, and Nucleus UUID(s), where applicable, will be stored in Nucleus as an Audit Log, and the resulting audit_log_id will be returned in the Proton response. Audit logs created here can be utilized by the Card Authorization service. Defaults to false.

Example Response

{
    "as_of_date": "2020-12-15T00:00:00.000+0000",
    "currency_code": "USD",
    "summary": {
        "number_of_limits": 6,
        "number_of_limits_breached": 1,
        "number_of_limits_unbreached": 5
    },
    "limit_check": [
        {
            "spending_control_id": "45e1a978-bf92-43b9-a26f-998738622003",
            "control_type": "transaction_limit",
            "control_scope": "purchase",
            "control_values": [],
            "frequency_unit": "daily",
            "frequency": 1,
            "limit_value": 1,
            "limit_used": 1,
            "limit_remaining": 0,
            "limit_breached": true,
            "limit_start_date": "2020-12-15T00:00:00.000000+0000",
            "limit_reset_date": "2020-12-16T00:00:00.000000+0000",
            "days_until_limit_reset": 1,
            "is_primary_transaction_category": [],
            "primary_transaction_category_name": []
        },
        {
            "spending_control_id": "b34c9e4a-66fe-4840-b73a-7b5f3a9dd552",
            "control_type": "spending_limit",
            "control_scope": "purchase",
            "control_values": [],
            "frequency_unit": "annually",
            "frequency": 1,
            "limit_value": 15000.0,
            "limit_used": 2595.4,
            "limit_remaining": 12404.6,
            "limit_breached": false,
            "limit_start_date": "2020-01-01T00:00:00.000000+0000",
            "limit_reset_date": "2021-01-01T00:00:00.000000+0000",
            "days_until_limit_reset": 17,
            "is_primary_transaction_category": [],
            "primary_transaction_category_name": []
        },
        {
            "spending_control_id": "591627da-f3d2-4ee0-bb6b-7838dbee3c36",
            "control_type": "spending_limit",
            "control_scope": "atm_withdrawal",
            "control_values": [],
            "frequency_unit": "one_time",
            "frequency": 1,
            "limit_value": 2000.0,
            "limit_used": 0,
            "limit_remaining": 2000.0,
            "limit_breached": false,
            "limit_start_date": null,
            "limit_reset_date": null,
            "days_until_limit_reset": null,
            "is_primary_transaction_category": [],
            "primary_transaction_category_name": []
        },
        {
            "spending_control_id": "60d45207-b17a-4965-bd01-690ffbea0578",
            "control_type": "spending_limit",
            "control_scope": "transaction_category",
            "control_values": [
                "Pets"
            ],
            "frequency_unit": "monthly",
            "frequency": 1,
            "limit_value": 1000.0,
            "limit_used": 253.34,
            "limit_remaining": 746.66,
            "limit_breached": false,
            "limit_start_date": "2020-12-01T00:00:00.000000+0000",
            "limit_reset_date": "2021-01-01T00:00:00.000000+0000",
            "days_until_limit_reset": 17,
            "is_primary_transaction_category": [],
            "primary_transaction_category_name": []
        },
        {
            "spending_control_id": "60d45207-b17a-4965-bd01-690ffbea0578",
            "control_type": "spending_limit",
            "control_scope": "transaction_category",
            "control_values": [
                "Personal Care"
            ],
            "frequency_unit": "monthly",
            "frequency": 1,
            "limit_value": 1000.0,
            "limit_used": 47.89,
            "limit_remaining": 952.11,
            "limit_breached": false,
            "limit_start_date": "2020-12-01T00:00:00.000000+0000",
            "limit_reset_date": "2021-01-01T00:00:00.000000+0000",
            "days_until_limit_reset": 17,
            "is_primary_transaction_category": [],
            "primary_transaction_category_name": []
        },
        {
            "spending_control_id": "60d45207-b17a-4965-bd01-690ffbea0578",
            "control_type": "spending_limit",
            "control_scope": "transaction_category",
            "control_values": [
                "Home"
            ],
            "frequency_unit": "monthly",
            "frequency": 1,
            "limit_value": 1000.0,
            "limit_used": 931.62,
            "limit_remaining": 68.38,
            "limit_breached": false,
            "limit_start_date": "2020-12-01T00:00:00.000000+0000",
            "limit_reset_date": "2021-01-01T00:00:00.000000+0000",
            "days_until_limit_reset": 17,
            "is_primary_transaction_category": [],
            "primary_transaction_category_name": []
        }
    ]
}

RESPONSE

Field Description
as_of_date Date and time as of which the analysis is conducted. If as_of_date was provided in the request, it is reflected here. If as_of_date was not provided, this value is derived dynamically.
currency_code Currency code associated with monetary response values.
summary Summary of spending and transaction limits for the client.
      number_of_limits Total number of limits.
      number_of_limits_breached Number of limits that have been breached.
      number_of_limits_unbreached Number of limits that have not been breached.
limit_check Detailed analysis of each spending and transaction limit.
      spending_control_id ID of the Nucleus Spending Control.
      control_type Type of the spending control. Value may be spending_limit or transaction_limit.
      control_scope Scope of the spending control. Value may be all, purchase, atm_withdrawal, transaction_category, transaction_category_id, merchant, merchant_id, or location.
      control_values Value of the spending control. Will be one of the control_values from the corresponding spending control.
      frequency_unit Frequency unit of the spending control. Value may be one_time, daily, weekly, monthly, quarterly, or annually.
      frequency Frequency of the spending control. Indicates the number of frequency_unit between each period.
      limit_value Value of the spending control limit.
      limit_used Value already used towards this spending control limit.
      limit_remaining Value that remains to be used towards this spending control limit.
      limit_breached Indicates if the limit has been breached. Value of true indicates that the limit has been breached, while false indicates that the limit has not been breached.
      limit_start_date Start date of the control period determined by as_of_date.
      limit_reset_date End date of the control period determined by as_of_date.
      days_until_limit_reset Days remaining in the control period, calculated as the difference between the as_of_date and the limit_reset_date.
      is_primary_transaction_category If the spending control has control_scope = transaction_category_id, indicates whether the control_value is a primary transaction_category_id. A value of true indicates that it is a primary transaction_category_id. See Transaction Categories.
      primary_transaction_category_name If the spending control has control_scope = transaction_category_id and control_value is a primary transaction_category_id, then this will be the name of the category. See Transaction Categories.
audit_log_id The ID of the Audit Log record created in Nucleus. Only returned when create_log = true.

NUCLEUS DATA DEPENDENCIES

Financial Calculators

Education Planning Calculator

When planning for a future education expense, users face common questions when deciding where or when to attend. This tool helps in the decision process with three different endpoints to solve for the following parameters: deposit amount, percent of costs covered, and total annual cost. With these calculators, the user will be able to determine how much needs to be saved to attend a particular school, or what schools would be affordable given their financial circumstances. For all calculators, deposits are assumed to continue through the decumulation phase.

Deposit Amount

A calculator to help plan for an education goal by showing the user the amount that needs to be deposited for a given period.

HTTP REQUEST

POST /education_calculator/deposit_amount

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
         "initial_balance": 5000,
         "accumulation_horizon": 3,
         "decumulation_horizon": 4,
         "total_annual_cost": 40000,
         "portfolio_return": 0.06,
         "percent_of_costs_covered": 0.78,
         "education_inflation_rate": 0.05,
         "general_inflation_rate": 0.02,
         "tax_rate": 0.33,
         "deposit_schedule": {
            "deposit_frequency_interval": "year",
            "adjust_deposit_for_inflation": true
         }
      }' "https://api.hydrogenplatform.com/proton/v1/education_calculator/deposit_amount"
AnnuitiesApi annuitiesApi= new AnnuitiesApi();
        AnnuityCalculatorDepositAmountRequest annuityCalculatorDepositAmountRequest =
                new AnnuityCalculatorDepositAmountRequest();
        annuityCalculatorDepositAmountRequest.setPortfolioReturn(0.1F);
        annuityCalculatorDepositAmountRequest.setAccumulationHorizon(3);
        annuityCalculatorDepositAmountRequest.setDecumulationHorizon(2);
        annuityCalculatorDepositAmountRequest.setAnnuityAmount(3000F);
        annuityCalculatorDepositAmountRequest.setAnnuityFrequencyInterval(AnnuityCalculatorDepositAmountRequest.AnnuityFrequencyIntervalEnum.YEAR);
        annuityCalculatorDepositAmountRequest.setInflationRate(0.02F);
        annuityCalculatorDepositAmountRequest.setTaxRate(0.25F);
        AnnuityDepositSchedule depositScheduleAmountReq =  new AnnuityDepositSchedule();
        depositScheduleAmountReq.setDepositFrequencyInterval(AnnuityDepositSchedule.DepositFrequencyIntervalEnum.YEAR);
        depositScheduleAmountReq.setAdjustDepositForInflation(TRUE);
        depositScheduleAmountReq.setDepositAmount(200F);
        annuityCalculatorDepositAmountRequest.setDepositSchedule(depositScheduleAmountReq);
        annuityCalculatorDepositAmountRequest.setAccountIds(Arrays.asList(
                UUID.fromString("eb522e3c-5462-49ae-9315-048aeffad2e3")
        ));
        Map<String, Object> annuityCalculatorDepositAmountResponse = annuitiesApi.annuityCalculatorDepositAmount(annuityCalculatorDepositAmountRequest);
        System.out.println(annuityCalculatorDepositAmountResponse);
api_instance = proton_api.AnnuitiesApi(proton_api.ApiClient(configuration))
annuity_calculator_deposit_amount_request = proton_api.AnnuityCalculatorDepositAmountRequest(decumulation_horizon = 2,
 accumulation_horizon = 3,
 annuity_amount = 3000,
 portfolio_return = 0.1)
annuity_calculator_deposit_amount_request.annuity_frequency_interval = 'year'
annuity_calculator_deposit_amount_request.deposit_schedule = annuity_deposit_schedule
annuity_calculator_deposit_amount_request.account_ids = ["eb522e3c-5462-49ae-9315-048aeffad2e3"]
try:
    # Annuity Calculator - Deposit Amount
    api_response = api_instance.annuity_calculator_deposit_amount(annuity_calculator_deposit_amount_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling AnnuitiesApi->annuity_calculator_deposit_amount: %s\n" % e)
api_instance = ProtonApi::AnnuitiesApi.new
annuityCalculatorDepositAmountRequest = ProtonApi::AnnuityCalculatorDepositAmountRequest.new
begin
  annuityCalculatorDepositAmountRequest.portfolio_return = 0.1
  annuityCalculatorDepositAmountRequest.annuity_amount = 3000
  annuityCalculatorDepositAmountRequest.accumulation_horizon = 3
  annuityCalculatorDepositAmountRequest.decumulation_horizon = 2
  annuityCalculatorDepositAmountRequest.annuity_frequency_interval = "year"
  annuityCalculatorDepositAmountRequest.inflation_rate = 0.02
  annuityCalculatorDepositAmountRequest.tax_rate = 0.25
  annuityCalculatorDepositAmountRequest.account_ids = ["eb522e3c-5462-49ae-9315-048aeffad2e3"]
  annuityDepositSchedule.deposit_amount = 200
  annuityDepositSchedule.deposit_frequency_interval = 'year'
  annuityDepositSchedule.adjust_deposit_for_inflation = true
  annuityCalculatorDepositAmountRequest.deposit_schedule = annuityDepositSchedule
  annuityCalculatorDepositResponse = api_instance.annuity_calculator_deposit_amount(annuityCalculatorDepositAmountRequest)
  p annuityCalculatorDepositResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling annuity_Calculator_Deposit_Amount_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\AnnuitiesApi(
    new GuzzleHttp\Client(),
    $config
);
$annuityCalculatorDepositAmountRequest = new com\hydrogen\proton\Model\AnnuityCalculatorDepositAmountRequest();
try {

    $annuityCalculatorDepositAmountRequest->setportfolioreturn(0.1);
    $annuityCalculatorDepositAmountRequest->setaccumulationhorizon(3);
    $annuityCalculatorDepositAmountRequest->setdecumulationhorizon(2);
    $annuityCalculatorDepositAmountRequest->setannuityamount(3000);
    $annuityCalculatorDepositAmountRequest->setannuityfrequencyinterval("year");
    $annuityCalculatorDepositAmountRequest->setinflationrate(0.02);
    $annuityCalculatorDepositAmountRequest->settaxrate(0.25);
    $depositone = new \com\hydrogen\proton\Model\AnnuityDepositSchedule();
    $depositone->setDepositAmount(200);
    $depositone->setDepositFrequencyInterval("year");
    $depositone->setAdjustDepositForInflation(true);
    $annuityCalculatorDepositAmountRequest->setDepositSchedule($depositone);
    $annuityCalculatorDepositAmountRequest->setAccountIds(["eb522e3c-5462-49ae-9315-048aeffad2e3"]);
    $result = $apiInstance->annuityCalculatorDepositAmount($annuityCalculatorDepositAmountRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling IntegrationAPI->createUserUsingPost: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.AnnuitiesApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
    var api = new HydrogenProtonApi.AnnuitiesApi();
    var annuityCalculatorDepositAmountRequest = new HydrogenProtonApi.AnnuityCalculatorDepositAmountRequest()
    annuityCalculatorDepositAmountRequest.portfolio_return = 0.1;
    annuityCalculatorDepositAmountRequest.annuity_amount = 3000;
    annuityCalculatorDepositAmountRequest.initial_balance = 2000;
    annuityCalculatorDepositAmountRequest.accumulation_horizon = 3;
    annuityCalculatorDepositAmountRequest.decumulation_horizon = 2;
    annuityCalculatorDepositAmountRequest.annuity_frequency_interval = "year";
    annuityCalculatorDepositAmountRequest.inflation_rate = 0.02;
    annuityCalculatorDepositAmountRequest.tax_rate = 0.25;
    annuityCalculatorDepositAmountRequest.accountIds = ["eb522e3c-5462-49ae-9315-048aeffad2e3"]
    annuityCalculatorDepositAmountRequest.deposit_schedule = {
        deposit_amount: 500,
        deposit_frequency_interval: "year",
        adjust_deposit_for_inflation: true
    };

    api.annuityCalculatorDepositAmount(annuityCalculatorDepositAmountRequest, callback);

ARGUMENTS

Parameter Description
accumulation_horizon
integer, required
The amount of years until funds are needed to pay for an education expense.
decumulation_horizon
integer, required
The number of years to pay the total_annual_cost.
total_annual_cost
float, required
The total cost paid per year for the education goal, represented in today’s dollars.
portfolio_return
float, required
The portfolio return for the length of the accumulation_horizon and decumulation_horizon.
percent_of_costs_covered
float
The percentage of total_annual_cost to be paid for. If excluded, defaults to 1.
initial_balance
float
The amount currently saved for the education goal. If excluded, defaults to 0.
education_inflation_rate
float
The inflation rate attributed to total_annual_cost. If excluded, defaults to 0.05.
general_inflation_rate
float
The rate used to increase deposits for inflation. If excluded, defaults to 0.02.
tax_rate
float
The tax rate to apply to investments upon removal from the portfolio. If excluded, defaults to 0.
deposit_schedule
map
The deposit schedule for the education goal.
      deposit_frequency_interval
      string
The period interval to be used in relation to the deposit_amount. The value may be one of the following: year, quarter, month, or week. If excluded, defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposits should be increased over time with the rate of inflation. If excluded, defaults to true.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive initial_balance. If initial_balance is not provided, we will try to use account_ids to derive this value instead.

Example Response

{
    "deposit_amount": 37564.93,
    "deposit_frequency_interval": "year",
    "projected_accumulation_savings": 127860.79,
    "total_earnings": 28506.82,
    "total_contributions": 279268.34,
    "total_cost": 209559.36,
    "total_taxes": 103215.8,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 5000
        },
        "1": {
            "period_earnings": 300,
            "period_contribution": 37564.93,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 37564.93,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 42864.93
        },
        "2": {
            "period_earnings": 2571.9,
            "period_contribution": 38316.23,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 2871.9,
            "cumulative_contributions": 75881.16,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 83753.06
        },
        "3": {
            "period_earnings": 5025.18,
            "period_contribution": 39082.55,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 7897.08,
            "cumulative_contributions": 114963.71,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 127860.79
        },
        "4": {
            "period_earnings": 7671.65,
            "period_contribution": 39864.2,
            "period_withdrawal": -48620.25,
            "period_taxes": -23947.29,
            "cumulative_earnings": 15568.73,
            "cumulative_contributions": 154827.92,
            "cumulative_withdrawals": -48620.25,
            "cumulative_taxes": -23947.29,
            "ending_balance": 102829.11
        },
        "5": {
            "period_earnings": 6169.75,
            "period_contribution": 40661.49,
            "period_withdrawal": -51051.26,
            "period_taxes": -25144.65,
            "cumulative_earnings": 21738.47,
            "cumulative_contributions": 195489.41,
            "cumulative_withdrawals": -99671.51,
            "cumulative_taxes": -49091.94,
            "ending_balance": 73464.43
        },
        "6": {
            "period_earnings": 4407.87,
            "period_contribution": 41474.72,
            "period_withdrawal": -53603.83,
            "period_taxes": -26401.88,
            "cumulative_earnings": 26146.34,
            "cumulative_contributions": 236964.13,
            "cumulative_withdrawals": -153275.34,
            "cumulative_taxes": -75493.82,
            "ending_balance": 39341.3
        },
        "7": {
            "period_earnings": 2360.48,
            "period_contribution": 42304.21,
            "period_withdrawal": -56284.02,
            "period_taxes": -27721.98,
            "cumulative_earnings": 28506.82,
            "cumulative_contributions": 279268.34,
            "cumulative_withdrawals": -209559.36,
            "cumulative_taxes": -103215.8,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
deposit_amount The deposit amount to meet the education goal.
deposit_frequency_interval The period interval associated with deposit_amount.
projected_accumulation_savings The projected balance at the end of accumulation_horizon.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_cost The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      period_contribution
      
The deposit made for this period.
      period_withdrawal
      
The withdrawal made for this period.
      period_taxes
      
The taxes paid during this period.
      cumulative_earnings
      
The cumulative investment earnings made up to and including this period.
      cumulative_contributions
      
The cumulative deposits made up to and including this period.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_taxes
      
The cumulative taxes paid up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Percent of Costs Covered

A calculator to help plan for an education goal by solving for the percentage of the total cost that the user can afford.

HTTP REQUEST

POST /education_calculator/percent_covered

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
         "initial_balance": 5000,
         "accumulation_horizon": 3,
         "decumulation_horizon": 4,
         "total_annual_cost": 40000,
         "portfolio_return": 0.06,
         "education_inflation_rate": 0.05,
         "general_inflation_rate": 0.02,
         "tax_rate": 0.33,
         "deposit_schedule": {
            "deposit_amount": 4000,
            "deposit_frequency_interval": "year",
            "adjust_deposit_for_inflation": true
         }
      }' "https://api.hydrogenplatform.com/proton/v1/education_calculator/percent_covered"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
EducationCalculatorPercentCoveredRequest educationCalculatorPercentCoveredRequest = new EducationCalculatorPercentCoveredRequest();
educationCalculatorPercentCoveredRequest.setInitialBalance(5000F);
educationCalculatorPercentCoveredRequest.setAccumulationHorizon(3);
educationCalculatorPercentCoveredRequest.setDecumulationHorizon(4);
educationCalculatorPercentCoveredRequest.setTotalAnnualCost(4000F);
educationCalculatorPercentCoveredRequest.setPortfolioReturn(0.06F);
educationCalculatorPercentCoveredRequest.setEducationInflationRate(0.05F);
educationCalculatorPercentCoveredRequest.setGeneralInflationRate(0.02F);
educationCalculatorPercentCoveredRequest.setTaxRate(0.33F);
CalculatorDepositSchedule1 calculatorDepositSchedule1 = new CalculatorDepositSchedule1();
calculatorDepositSchedule1.setDepositAmount(4000F);
calculatorDepositSchedule1.setDepositFrequencyInterval(CalculatorDepositSchedule1.DepositFrequencyIntervalEnum.YEAR);
calculatorDepositSchedule1.setAdjustDepositForInflation(Boolean.TRUE);
educationCalculatorPercentCoveredRequest.setDepositSchedule(calculatorDepositSchedule1);
Map<String, Object> educationCalculatorPercentCoveredResponse =
        financialPlanningApi.educationCalculatorPercentCovered(educationCalculatorPercentCoveredRequest);
System.out.println(educationCalculatorPercentCoveredResponse);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
education_calculator_percent_covered = proton_api.EducationCalculatorPercentCoveredRequest(
    initial_balance=5000, accumulation_horizon=3, decumulation_horizon=4, total_annual_cost=4000,
    portfolio_return=0.06, education_inflation_rate=0.05, general_inflation_rate=0.02, tax_rate=0.33,
    deposit_schedule=proton_api.CalculatorDepositSchedule1(
        deposit_amount=4000, deposit_frequency_interval='year', adjust_deposit_for_inflation=True
    )
)
try:
    # Financial Planning - Education Calculator Percent Covered
    api_response = api_instance.education_calculator_percent_covered(education_calculator_percent_covered)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->education_calculator_percent_covered: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
educationCalculatorPercentCoveredRequest = ProtonApi::EducationCalculatorPercentCoveredRequest.new
begin
  educationCalculatorPercentCoveredRequest.initial_balance = 5000
  educationCalculatorPercentCoveredRequest.accumulation_horizon = 3
  educationCalculatorPercentCoveredRequest.decumulation_horizon = 4
  educationCalculatorPercentCoveredRequest.total_annual_cost = 40000
  educationCalculatorPercentCoveredRequest.portfolio_return = 0.06
  educationCalculatorPercentCoveredRequest.education_inflation_rate = 0.05
  educationCalculatorPercentCoveredRequest.general_inflation_rate = 0.02
  educationCalculatorPercentCoveredRequest.tax_rate = 0.33
  calculatorDepositSchedule.deposit_frequency_interval = 'year'
  calculatorDepositSchedule.deposit_amount = 4000
  calculatorDepositSchedule.adjust_deposit_for_inflation = true
  educationCalculatorPercentCoveredRequest.deposit_schedule = calculatorDepositSchedule
  educationCalculatorPercentCoveredResponse = api_instance.education_calculator_percent_covered(educationCalculatorPercentCoveredRequest)
  p educationCalculatorPercentCoveredResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling education_Calculator_Percent_Covered_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$educationCalculatorPercentCoveredRequest = new com\hydrogen\proton\Model\EducationCalculatorPercentCoveredRequest();
try {

    $educationCalculatorPercentCoveredRequest->setinitialbalance(5000);
    $educationCalculatorPercentCoveredRequest->setaccumulationhorizon(3);
    $educationCalculatorPercentCoveredRequest->setdecumulationhorizon(4);
    $educationCalculatorPercentCoveredRequest->setportfolioreturn(0.06);
    $educationCalculatorPercentCoveredRequest->settotalannualcost(40000);
    $educationCalculatorPercentCoveredRequest->seteducationinflationrate(0.05);
    $educationCalculatorPercentCoveredRequest->setgeneralinflationrate(0.02);
    $educationCalculatorPercentCoveredRequest->settaxrate(0.33);
    $depositCalculatorPercent = new \com\hydrogen\proton\Model\CalculatorDepositSchedule1();
    $depositCalculatorPercent->setDepositAmount(4000);
    $depositCalculatorPercent->setDepositFrequencyInterval('year');
    $depositCalculatorPercent->setAdjustDepositForInflation(true);
    $educationCalculatorPercentCoveredRequest->setDepositSchedule($depositCalculatorPercent);
    $result = $apiInstance->educationCalculatorPercentCovered($educationCalculatorPercentCoveredRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->educationCalculatorPercentCovered: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
    var educationCalculatorPercentCoveredRequest = new HydrogenProtonApi.EducationCalculatorPercentCoveredRequest();
    educationCalculatorPercentCoveredRequest.initial_balance = 5000;
    educationCalculatorPercentCoveredRequest.accumulation_horizon = 3;
    educationCalculatorPercentCoveredRequest.decumulation_horizon = 4;
    educationCalculatorPercentCoveredRequest.total_annual_cost = 40000;
    educationCalculatorPercentCoveredRequest.portfolio_return = 0.06;
    educationCalculatorPercentCoveredRequest.education_inflation_rate = 0.05;
    educationCalculatorPercentCoveredRequest.general_inflation_rate = 0.02;
    educationCalculatorPercentCoveredRequest.tax_rate = 0.33;
    educationCalculatorPercentCoveredRequest.deposit_schedule = {
        deposit_amount: 4000,
        deposit_frequency_interval: "year",
        adjust_deposit_for_inflation: true
    };
    api.educationCalculatorPercentCovered(educationCalculatorPercentCoveredRequest, callback);

ARGUMENTS

Parameter Description
accumulation_horizon
integer, required
The amount of years until funds are needed to pay for an education expense.
decumulation_horizon
integer, required
The number of years to pay the total_annual_cost.
total_annual_cost
float, required
The total cost paid per year for the education goal, represented in today’s dollars.
portfolio_return
float, required
The portfolio return for the length of the accumulation_horizon and decumulation_horizon.
initial_balance
float
The amount currently saved for the education goal. If excluded, defaults to 0.
education_inflation_rate
float
The inflation rate attributed to total_annual_cost. If excluded, defaults to 0.05.
general_inflation_rate
float
The rate used to increase deposits for inflation. If excluded, defaults to 0.02.
tax_rate
float
The tax rate to apply to investments upon removal from the portfolio. If excluded, defaults to 0.
deposit_schedule
map
The deposit schedule for the education goal.
      deposit_amount
      float
The amount deposited per a given period & number of intervals. Deposits are assumed to continue through the length of accumulation_horizon and decumulation_horizon. If excluded, defaults to 0.
      deposit_frequency_interval
      string
The period interval to be used in relation to the deposit_amount. The value may be one of the following: year, quarter, month, or week. If excluded, defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposits should be increased over time with the rate of inflation. If excluded, defaults to true.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive initial_balance. If initial_balance is not provided, we will try to use account_ids to derive this value instead.

Example Response

{
    "achievable_cost": 5047.62,
    "target_cost": 40000,
    "percent_of_costs_covered": 0.1262,
    "projected_accumulation_savings": 18935.88,
    "total_earnings": 4732.09,
    "total_contributions": 29737.13,
    "total_cost": 26444.38,
    "total_taxes": 13024.84,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 5000
        },
        "1": {
            "period_earnings": 300,
            "period_contribution": 4000,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 4000,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 9300
        },
        "2": {
            "period_earnings": 558,
            "period_contribution": 4080,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 858,
            "cumulative_contributions": 8080,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 13938
        },
        "3": {
            "period_earnings": 836.28,
            "period_contribution": 4161.6,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 1694.28,
            "cumulative_contributions": 12241.6,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 18935.88
        },
        "4": {
            "period_earnings": 1136.15,
            "period_contribution": 4244.83,
            "period_withdrawal": -6135.41,
            "period_taxes": -3021.92,
            "cumulative_earnings": 2830.43,
            "cumulative_contributions": 16486.43,
            "cumulative_withdrawals": -6135.41,
            "cumulative_taxes": -3021.92,
            "ending_balance": 15159.54
        },
        "5": {
            "period_earnings": 909.57,
            "period_contribution": 4329.73,
            "period_withdrawal": -6442.18,
            "period_taxes": -3173.01,
            "cumulative_earnings": 3740.01,
            "cumulative_contributions": 20816.16,
            "cumulative_withdrawals": -12577.59,
            "cumulative_taxes": -6194.93,
            "ending_balance": 10783.65
        },
        "6": {
            "period_earnings": 647.02,
            "period_contribution": 4416.32,
            "period_withdrawal": -6764.29,
            "period_taxes": -3331.66,
            "cumulative_earnings": 4387.02,
            "cumulative_contributions": 25232.48,
            "cumulative_withdrawals": -19341.88,
            "cumulative_taxes": -9526.6,
            "ending_balance": 5751.04
        },
        "7": {
            "period_earnings": 345.06,
            "period_contribution": 4504.65,
            "period_withdrawal": -7102.5,
            "period_taxes": -3498.25,
            "cumulative_earnings": 4732.09,
            "cumulative_contributions": 29737.13,
            "cumulative_withdrawals": -26444.38,
            "cumulative_taxes": -13024.84,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
achievable_cost The annual cost that can be covered, expressed in today’s dollars.
target_cost The total_annual_cost input representing the target annual goal amount.
percent_of_costs_covered The percentage of target_cost that can be covered.
projected_accumulation_savings The projected balance at the end of accumulation_horizon.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_cost The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      period_contribution
      
The deposit made for this period.
      period_withdrawal
      
The withdrawal made for this period.
      period_taxes
      
The taxes paid during this period.
      cumulative_earnings
      
The cumulative investment earnings made up to and including this period.
      cumulative_contributions
      
The cumulative deposits made up to and including this period.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_taxes
      
The cumulative taxes paid up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Total Annual Cost

A calculator to help plan for an education goal by solving for the total annual cost that a user could afford.

HTTP REQUEST

POST /education_calculator/annual_cost

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "initial_balance": 5000,
        "accumulation_horizon": 3,
        "decumulation_horizon": 4,
        "portfolio_return": 0.06,
        "percent_of_costs_covered": 1,
        "education_inflation_rate": 0.05,
        "general_inflation_rate": 0.02,
        "tax_rate": 0.33,
        "deposit_schedule": {
            "deposit_amount": 4000,
            "deposit_frequency_interval": "year",
            "adjust_deposit_for_inflation": true
        }
      }' "https://api.hydrogenplatform.com/proton/v1/education_calculator/annual_cost"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
EducationCalculatorAnnualCostRequest educationCalculatorAnnualCostRequest =
        new EducationCalculatorAnnualCostRequest();
educationCalculatorAnnualCostRequest.setInitialBalance(5000F);
educationCalculatorAnnualCostRequest.setAccumulationHorizon(3);
educationCalculatorAnnualCostRequest.setDecumulationHorizon(4);
educationCalculatorAnnualCostRequest.setPortfolioReturn(0.06F);
educationCalculatorAnnualCostRequest.setPercentOfCostsCovered(1F);
educationCalculatorAnnualCostRequest.setEducationInflationRate(0.05F);
educationCalculatorAnnualCostRequest.setGeneralInflationRate(0.02F);
Map<String, Object> educationCalculatorAnnualCostResponse =
        financialPlanningApi.educationCalculatorAnnualCost(educationCalculatorAnnualCostRequest);
System.out.println(educationCalculatorAnnualCostResponse);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
education_calculator_annual_cost_request = proton_api.EducationCalculatorAnnualCostRequest(
    initial_balance=5000, accumulation_horizon=3, decumulation_horizon=4, portfolio_return=0.06,
    percent_of_costs_covered=1,
    education_inflation_rate=0.05, general_inflation_rate=0.02
);
try:
    # Financial Planning - Education Calculator Annual Cost
    api_response = api_instance.education_calculator_annual_cost(education_calculator_annual_cost_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->education_calculator_annual_cost: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
educationCalculatorAnnualCostRequest = ProtonApi::EducationCalculatorAnnualCostRequest.new
begin
  educationCalculatorAnnualCostRequest.initial_balance = 5000
  educationCalculatorAnnualCostRequest.accumulation_horizon = 3
  educationCalculatorAnnualCostRequest.decumulation_horizon = 4
  educationCalculatorAnnualCostRequest.portfolio_return = 0.6
  educationCalculatorAnnualCostRequest.percent_of_costs_covered = 1
  educationCalculatorAnnualCostRequest.education_inflation_rate = 0.05
  educationCalculatorAnnualCostRequest.general_inflation_rate = 0.02
  education_calculator_response = api_instance.education_calculator_annual_cost(educationCalculatorAnnualCostRequest)
  p education_calculator_response
rescue ProtonApi::ApiError => e
  puts "Exception when calling education_Calculator_Annual_Cost_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$educationCalculatorAnnualCostRequest = new com\hydrogen\proton\Model\EducationCalculatorAnnualCostRequest();
try {

    $educationCalculatorAnnualCostRequest->setinitialbalance(5000);
    $educationCalculatorAnnualCostRequest->setdecumulationhorizon(4);
    $educationCalculatorAnnualCostRequest->setportfolioreturn(0.6);
    $educationCalculatorAnnualCostRequest->setpercentofcostscovered(1);
    $educationCalculatorAnnualCostRequest->seteducationinflationrate(0.05);
    $educationCalculatorAnnualCostRequest->setgeneralinflationrate(0.02);
    $educationCalculatorAnnualCostRequest->settaxrate(0.33);
    $educationCalculatorAnnualCostRequest->setAccumulationHorizon(3);
    $result = $apiInstance->educationCalculatorAnnualCost($educationCalculatorAnnualCostRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->educationCalculatorAnnualCost: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
    var api = new HydrogenProtonApi.FinancialPlanningApi();
    var educationCalculatorAnnualCostRequest = new HydrogenProtonApi.EducationCalculatorAnnualCostRequest();
    educationCalculatorAnnualCostRequest.initial_balance = 5000;
    educationCalculatorAnnualCostRequest.accumulation_horizon = 3;
    educationCalculatorAnnualCostRequest.decumulation_horizon = 4;
    educationCalculatorAnnualCostRequest.portfolio_return = 0.6;
    educationCalculatorAnnualCostRequest.percent_of_costs_covered=1;
    educationCalculatorAnnualCostRequest.education_inflation_rate = 0.05;
    educationCalculatorAnnualCostRequest.general_inflation_rate = 0.02;

    api.educationCalculatorAnnualCost(educationCalculatorAnnualCostRequest, callback);

ARGUMENTS

Parameter Description
accumulation_horizon
integer, required
The amount of years until funds are needed to pay for an education expense.
decumulation_horizon
integer, required
The number of years to pay the total_annual_cost.
portfolio_return
float, required
The portfolio return for the length of the accumulation_horizon and decumulation_horizon.
percent_of_costs_covered
float
The percentage of total_annual_cost to be paid for. If excluded, defaults to 1.
initial_balance
float
The amount currently saved for the education goal. If excluded, defaults to 0.
education_inflation_rate
float
The inflation rate attributed to total_annual_cost. If excluded, defaults to 0.05.
general_inflation_rate
float
The rate used to increase deposits for inflation. If excluded, defaults to 0.02.
tax_rate
float
The tax rate to apply to investments upon removal from the portfolio. If excluded, defaults to 0.
deposit_schedule
map
The deposit schedule for the education goal.
      deposit_amount
      float
The amount deposited per a given period & number of intervals. Deposits are assumed to continue through the length of accumulation_horizon and decumulation_horizon. If excluded, defaults to 0.
      deposit_frequency_interval
      string
The period interval to be used in relation to the deposit_amount. The value may be one of the following: year, quarter, month, or week. If excluded, defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposits should be increased over time with the rate of inflation. If excluded, defaults to true.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive initial_balance. If initial_balance is not provided, we will try to use account_ids to derive this value instead.

Example Response

{
    "total_annual_cost": 6135.41,
    "total_annual_cost_adjusted": 5047.62,
    "projected_accumulation_savings": 18935.88,
    "total_earnings": 4732.09,
    "total_contributions": 29737.13,
    "total_cost": 26444.38,
    "total_taxes": 13024.84,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 5000
        },
        "1": {
            "period_earnings": 300,
            "period_contribution": 4000,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 4000,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 9300
        },
        "2": {
            "period_earnings": 558,
            "period_contribution": 4080,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 858,
            "cumulative_contributions": 8080,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 13938
        },
        "3": {
            "period_earnings": 836.28,
            "period_contribution": 4161.6,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 1694.28,
            "cumulative_contributions": 12241.6,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 18935.88
        },
        "4": {
            "period_earnings": 1136.15,
            "period_contribution": 4244.83,
            "period_withdrawal": -6135.41,
            "period_taxes": -3021.92,
            "cumulative_earnings": 2830.43,
            "cumulative_contributions": 16486.43,
            "cumulative_withdrawals": -6135.41,
            "cumulative_taxes": -3021.92,
            "ending_balance": 15159.54
        },
        "5": {
            "period_earnings": 909.57,
            "period_contribution": 4329.73,
            "period_withdrawal": -6442.18,
            "period_taxes": -3173.01,
            "cumulative_earnings": 3740.01,
            "cumulative_contributions": 20816.16,
            "cumulative_withdrawals": -12577.59,
            "cumulative_taxes": -6194.93,
            "ending_balance": 10783.65
        },
        "6": {
            "period_earnings": 647.02,
            "period_contribution": 4416.32,
            "period_withdrawal": -6764.29,
            "period_taxes": -3331.66,
            "cumulative_earnings": 4387.02,
            "cumulative_contributions": 25232.48,
            "cumulative_withdrawals": -19341.88,
            "cumulative_taxes": -9526.6,
            "ending_balance": 5751.04
        },
        "7": {
            "period_earnings": 345.06,
            "period_contribution": 4504.65,
            "period_withdrawal": -7102.5,
            "period_taxes": -3498.25,
            "cumulative_earnings": 4732.09,
            "cumulative_contributions": 29737.13,
            "cumulative_withdrawals": -26444.38,
            "cumulative_taxes": -13024.84,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
total_annual_cost The total education cost per year that can be afforded.
total_annual_cost_adjusted The total education cost per year that can be afforded, represented in today’s dollars.
projected_accumulation_savings The projected balance at the end of accumulation_horizon.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_cost The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      period_contribution
      
The deposit made for this period.
      period_withdrawal
      
The withdrawal made for this period.
      period_taxes
      
The taxes paid during this period.
      cumulative_earnings
      
The cumulative investment earnings made up to and including this period.
      cumulative_contributions
      
The cumulative deposits made up to and including this period.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_taxes
      
The cumulative taxes paid up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Emergency Fund Calculator

An emergency fund refers to a pool of money a user can rely on if they experience a loss of income. This fund should be able to cover all necessary expenses that the user would have to continue paying. The tool allows for the flexibility to use pre-set expense fields, or utilize an area for custom expenses. After specifying the number of months of expenses the emergency fund should cover, the calculator returns a total recommendation along with a plan to save for the total recommended amount in a variety of horizon intervals.

HTTP REQUEST

POST /emergency_fund_calculator

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "emergency_fund_duration": 12,
        "housing_cost": 1650,
        "utility_payments": 60,
        "telecom_payments": 50,
        "insurance_payments": 0,
        "debt_payments": 0,
        "transportation_costs": 150,
        "food_costs": 1500,
        "other_expenses":
        {
            "entertainment": 50,
            "daycare": 150
        },
        "current_emergency_fund_balance": 15000,
        "interest_rate": 0.015,
        "savings_horizon": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24],
        "frequency_unit": "month"
    }' "https://api.hydrogenplatform.com/proton/v1/emergency_fund_calculator"
FinancialHealthApi financialHealthApi = new FinancialHealthApi();
EmergencyFundCalculatorRequest emergencyFundCalculatorRequest =
        new EmergencyFundCalculatorRequest();
emergencyFundCalculatorRequest.setEmergencyFundDuration(12);
emergencyFundCalculatorRequest.setHousingCost(1650F);
emergencyFundCalculatorRequest.setUtilityPayments(60F);
emergencyFundCalculatorRequest.setTelecomPayments(50F);
emergencyFundCalculatorRequest.setInsurancePayments(0F);
emergencyFundCalculatorRequest.setDebtPayments(0F);
emergencyFundCalculatorRequest.setTransportationCosts(150F);
emergencyFundCalculatorRequest.setFoodCosts(1500F);
Map<String, Object> otherExpense = new HashMap<>();
otherExpense.put("entertainment", 50);
otherExpense.put("daycare", 150);
emergencyFundCalculatorRequest.setOtherExpenses(otherExpense);
emergencyFundCalculatorRequest.setCurrentEmergencyFundBalance(15000F);
emergencyFundCalculatorRequest.setInterestRate(0.015F);
emergencyFundCalculatorRequest.setSavingsHorizon(Arrays
.asList(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24));
emergencyFundCalculatorRequest.setFrequencyUnit(EmergencyFundCalculatorRequest.FrequencyUnitEnum.MONTH);
Map<String, Object> emergencyFundCalculatorResponse =
        financialHealthApi.emergencyFundCalculator(emergencyFundCalculatorRequest);
System.out.println(emergencyFundCalculatorResponse);
api_instance = proton_api.FinancialHealthApi(proton_api.ApiClient(configuration))
emergency_fund_calculator_request = proton_api.EmergencyFundCalculatorRequest(
    emergency_fund_duration=12, housing_cost=1650, utility_payments=60, telecom_payments=50, insurance_payments=0,
    debt_payments=0, transportation_costs=150, food_costs=1500, other_expenses={
        "entertainment" : 50,
        "daycare" : 150
    }, current_emergency_fund_balance=15000, interest_rate=0.015,
    savings_horizon=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24],
    frequency_unit='month'
)
try:
    # Financial Health - Emergency Fund Calculator
    api_response = api_instance.emergency_fund_calculator(emergency_fund_calculator_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialHealthApi->emergency_fund_calculator: %s\n" % e)
api_instance = ProtonApi::FinancialHealthApi.new
emergencyFundCalculatorRequest= ProtonApi::EmergencyFundCalculatorRequest.new
begin
  emergencyFundCalculatorRequest.housing_cost = 1650
  emergencyFundCalculatorRequest.utility_payments = 60
  emergencyFundCalculatorRequest.telecom_payments = 50
  emergencyFundCalculatorRequest.insurance_payments = 0
  emergencyFundCalculatorRequest.debt_payments = 0
  emergencyFundCalculatorRequest.transportation_costs = 150
  emergencyFundCalculatorRequest.food_costs = 1500
  emergencyFundCalculatorRequest.other_expenses = {
      "entertainment" => 50,
      "daycare" => 150
  }
  emergencyFundCalculatorRequest.current_emergency_fund_balance = 15000
  emergencyFundCalculatorRequest.interest_rate = 0.015
  emergencyFundCalculatorRequest.emergency_fund_duration = 12
  emergencyFundCalculatorRequest.savings_horizon = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24]
  emergencyFundCalculatorRequest.frequency_unit = 'month'
  emergencyFundCalculatorResponse = api_instance.emergency_fund_calculator(emergencyFundCalculatorRequest)
  p emergencyFundCalculatorResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling emergency_Fund_Calculator_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialHealthApi(
    new GuzzleHttp\Client(),
    $config
);
$emergencyFundCalculatorRequest = new com\hydrogen\proton\Model\EmergencyFundCalculatorRequest();
try {

    $emergencyFundCalculatorRequest->sethousingcost(1650);
    $emergencyFundCalculatorRequest->setutilitypayments(60);
    $emergencyFundCalculatorRequest->settelecompayments(50);
    $emergencyFundCalculatorRequest->setinsurancepayments(0);
    $emergencyFundCalculatorRequest->setdebtpayments(0);
    $emergencyFundCalculatorRequest->settransportationcosts(150);
    $emergencyFundCalculatorRequest->setfoodcosts(1500);
    $otherExpenses = new stdClass();
    $otherExpenses->entertainment = 50;
    $otherExpenses->daycare = 150;
    $emergencyFundCalculatorRequest->setotherexpenses($otherExpenses);
    $emergencyFundCalculatorRequest->setcurrentemergencyfundbalance(15000);
    $emergencyFundCalculatorRequest->setinterestrate(0.015);
    $emergencyFundCalculatorRequest->setEmergencyFundDuration(12);
    $emergencyFundCalculatorRequest->setsavingshorizon(array(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24));
    $emergencyFundCalculatorRequest->setfrequencyunit("month");
    $result = $apiInstance->emergencyFundCalculator($emergencyFundCalculatorRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialHealthAPI->emergencyFundCalculator: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialHealthApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
    var api = new HydrogenProtonApi.FinancialHealthApi();
    var emergencyFundCalculatorRequest = new HydrogenProtonApi.EmergencyFundCalculatorRequest();
    // {AnnuityCalculatorAccumulationHorizonRequest} Request payload for Annuity Calculator - Accumulation Horizon
    emergencyFundCalculatorRequest.housing_cost = 1650;
    emergencyFundCalculatorRequest.utility_payments = 60;
    emergencyFundCalculatorRequest.telecom_payments = 50;
    emergencyFundCalculatorRequest.insurance_payments = 0;
    emergencyFundCalculatorRequest.debt_payments = 0;
    emergencyFundCalculatorRequest.transportation_costs = 150;
    emergencyFundCalculatorRequest.food_costs = 1500;
    emergencyFundCalculatorRequest.other_expenses = {"entertainment": 50, "daycare": 150};
    emergencyFundCalculatorRequest.current_emergency_fund_balance = 15000;
    emergencyFundCalculatorRequest.interest_rate = 0.015;
    emergencyFundCalculatorRequest.emergency_fund_duration = 12;
    emergencyFundCalculatorRequest.savings_horizon = new Array(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24);
    emergencyFundCalculatorRequest.frequency_unit = 'month';
    api.emergencyFundCalculator(emergencyFundCalculatorRequest, callback);

ARGUMENTS

Parameter Description
emergency_fund_duration
integer, required
The number of periods (defined in frequency_unit) that the emergency fund will last.
housing_cost
float
The user’s housing costs, such as payments for rent, mortgage, maintenance, etc. If excluded, defaults to 0.
utility_payments
float
The user’s utility payments, such as electricity, water, gas, etc. If excluded, defaults to 0.
telecom_payments
float
The user’s telecom payments, such as internet, cell phone, cable, etc. If excluded, defaults to 0.
insurance_payments
float
The user’s payments for insurance, such as auto, home, motorcycle, etc. If excluded, defaults to 0.
debt_payments
float
The user’s debt payments, such as credit cards and loans. If excluded, defaults to 0.
transportation_costs
float
The user’s transportation costs, such as gasoline, car payments, etc. If excluded, defaults to 0.
food_costs
float
The user’s food costs, such as groceries, restaurants, etc. If excluded, defaults to 0.
other_expenses
map
A field to add any other expense type to be included in the emergency fund. If excluded, no additional expenses are included in the calculation.
      category_name
      string, required
The category name for each additional expense.
      amount
      float, required
The user’s total expense for each given category_name.
current_emergency_fund_balance
float
The user’s current balance of their emergency fund. If excluded, defaults to 0.
interest_rate
float
The annualized interest rate earned on the current_emergency_fund_balance used to calculate the recommended savings amount. The interest_rate is converted from annual rate to the appropriate frequency defined in frequency_unit. If excluded, defaults to 0.
savings_horizon
array
The periods in the savings horizon to be used in the recommended savings schedule. The period frequency is defined by frequency_unit. If excluded, defaults to [3, 6, 9, 12, 15, 18, 21, 24].
frequency_unit
string
The frequency unit that applies to emergency_fund_duration, all expenses, savings_horizon and saving_schedule. The value may be one of the following: year, quarter, month, two_weeks or week. If excluded, defaults to month.
client_id
UUID
The ID of a Nucleus client used to derive one or more of the following based on the client’s spending history: housing_cost, utility_payments, telecom_payments, insurance_payments, debt_payments, transportation_costs, and food_costs. If raw values for any of these optional parameters are not provided, we will use client_id to try to derive those values instead.
lookback_periods
integer
Number of periods to analyze when deriving expenses using a client_id. The unit of time associated with each period is based on frequency_unit, and expenses are averaged across all periods. Defaults to 3.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive current_emergency_fund_balance. If current_emergency_fund_balance is not provided, we will try to use account_ids to derive those values instead.

Example Response

{
    "emergency_fund_recommendation": 43320,
    "savings_schedule": {
        "1": 28320.0,
        "2": 14151.22,
        "3": 9428.29,
        "4": 7066.83,
        "5": 5649.95,
        "6": 4705.37,
        "7": 4030.67,
        "8": 3524.65,
        "9": 3131.07,
        "10": 2816.21,
        "11": 2558.6,
        "12": 2343.93,
        "13": 2162.28,
        "14": 2006.58,
        "15": 1871.65,
        "16": 1753.58,
        "17": 1649.4,
        "18": 1556.8,
        "19": 1473.94,
        "20": 1399.37,
        "21": 1331.91,
        "22": 1270.57,
        "23": 1214.57,
        "24": 1163.24
    }
}

RESPONSE

Field Description
emergency_fund_recommendation The total amount recommended for the user’s emergency fund.
savings_schedule The amount the user would need to save in order to achieve their emergency fund goal in a predefined amount of time.

NUCLEUS DATA DEPENDENCIES

Financial Health Check (Personal)

It is important to assess the health of a client’s financial situation in order to provide them with recommendations and guidance. This tool provides a financial health check by generating a series of financial ratios. After collecting information about the user’s assets, liabilities, income, and expenses, this tool returns ratio results and indicates a pass or fail based on a rule of thumb measure. The rule of thumb can be the system default or be overridden.

HTTP REQUEST

POST /financial_health_check

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "liquid_assets": 5000,
        "non_liquid_assets": 10000,
        "short_term_liabilities": 11000,
        "total_liabilities": 14000,
        "gross_annual_income": 60000,
        "net_monthly_income": 3500,
        "monthly_expenses": 3000,
        "ratio_targets": {
            "liquidity_ratio_expenses": 2.5,
            "liquidity_ratio_liabilities": 0.1,
            "current_ratio": 0.5,
            "asset_allocation_ratio": 1.5,
            "savings_ratio_gross": 0.1,
            "savings_ratio_net": 0.1
        }
    }' "https://api.hydrogenplatform.com/proton/v1/financial_health_check"
FinancialHealthApi financialHealthApi = new FinancialHealthApi();
FinancialHealthCheckRequest financialHealthCheckRequest = new FinancialHealthCheckRequest();
financialHealthCheckRequest.setLiquidAssets(5000F);
financialHealthCheckRequest.setNonLiquidAssets(10000F);
financialHealthCheckRequest.setShortTermLiabilities(11000F);
financialHealthCheckRequest.setTotalLiabilities(14000F);
financialHealthCheckRequest.setGrossAnnualIncome(6000F);
financialHealthCheckRequest.setNetMonthlyIncome(3500F);
financialHealthCheckRequest.setMonthlyExpenses(3000F);
RatioTargets ratioTargets = new RatioTargets();
ratioTargets.setLiquidityRatioExpenses(2.5F);
ratioTargets.setLiquidityRatioLiabilities(0.1F);
ratioTargets.setCurrentRatio(0.5F);
ratioTargets.setAssetAllocationRatio(1.5F);
ratioTargets.setSavingsRatioGross(0.1F);
ratioTargets.setSavingsRatioNet(0.1F);
financialHealthCheckRequest.setRatioTargets(ratioTargets);
Map<String, Object> financialHealthCheckResponse =
        financialHealthApi.financialHealthCheck(financialHealthCheckRequest);
System.out.println(financialHealthCheckResponse);
api_instance = proton_api.FinancialHealthApi(proton_api.ApiClient(configuration))
financial_health_check_request = proton_api.FinancialHealthCheckRequest(
    liquid_assets=5000, non_liquid_assets=10000, short_term_liabilities=11000, total_liabilities=14000,
    gross_annual_income=6000, net_monthly_income=3500, monthly_expenses=3000,
    ratio_targets=proton_api.RatioTargets(liquidity_ratio_expenses=2.5, liquidity_ratio_liabilities=0.1, current_ratio=0.5,
                                          asset_allocation_ratio=1.5, savings_ratio_gross=0.1, savings_ratio_net=0.1)
)
try:
    # Financial Health - Financial Health Check
    api_response = api_instance.financial_health_check(financial_health_check_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialHealthApi->financial_health_check: %s\n" % e)
api_instance = ProtonApi::FinancialHealthApi.new
financialHealthCheckRequest= ProtonApi::FinancialHealthCheckRequest.new
ratioTargets = ProtonApi::RatioTargets.new
begin
  financialHealthCheckRequest.liquid_assets = 5000
  financialHealthCheckRequest.non_liquid_assets = 10000
  financialHealthCheckRequest.short_term_liabilities = 11000
  financialHealthCheckRequest.total_liabilities = 14000
  financialHealthCheckRequest.gross_annual_income = 60000
  financialHealthCheckRequest.net_monthly_income = 3500
  financialHealthCheckRequest.monthly_expenses = 3000
  ratioTargets.liquidity_ratio_expenses =2.5
  ratioTargets.liquidity_ratio_liabilities =0.1
  ratioTargets.current_ratio =0.5
  ratioTargets.asset_allocation_ratio =1.5
  ratioTargets.savings_ratio_net =0.1
  ratioTargets.savings_ratio_gross =0.1
  financialHealthCheckRequest.ratio_targets = ratioTargets
  financialCheckResponse = api_instance.financial_health_check(financialHealthCheckRequest)
  p financialCheckResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling financial_Health_Check_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialHealthApi(
    new GuzzleHttp\Client(),
    $config
);
$financialHealthCheckRequest = new com\hydrogen\proton\Model\FinancialHealthCheckRequest();
try {
    $financialHealthCheckRequest->setLiquidAssets(5000);
    $financialHealthCheckRequest->setNonLiquidAssets(10000);
    $financialHealthCheckRequest->setShortTermLiabilities(11000);
    $financialHealthCheckRequest->setTotalLiabilities(14000);
    $financialHealthCheckRequest->setGrossAnnualIncome(60000);
    $financialHealthCheckRequest->setNetMonthlyIncome(3500);
    $financialHealthCheckRequest->setMonthlyExpenses(3000);
    $ratio_targets = new com\hydrogen\proton\Model\RatioTargets();
    $ratio_targets->setLiquidityRatioExpenses(2.5);
    $ratio_targets->setLiquidityRatioLiabilities(0.1);
    $ratio_targets->setCurrentRatio(0.5);;
    $ratio_targets->setAssetAllocationRatio(1.5);
    $ratio_targets->setSavingsRatioGross(0.1);
    $ratio_targets->setSavingsRatioNet(0.1);
    $financialHealthCheckRequest->setRatioTargets($ratio_targets);
    $result = $apiInstance->financialHealthCheck($financialHealthCheckRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialHealthAPI->financialHealthCheck: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialHealthApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialHealthApi();
    var financialHealthCheckRequest = new HydrogenProtonApi.FinancialHealthCheckRequest();
    financialHealthCheckRequest.liquid_assets = 5000;
    financialHealthCheckRequest.non_liquid_assets = 10000;
    financialHealthCheckRequest.short_term_liabilities = 11000;
    financialHealthCheckRequest.total_liabilities = 14000;
    financialHealthCheckRequest.gross_annual_income = 60000;
    financialHealthCheckRequest.net_monthly_income = 3500;
    financialHealthCheckRequest.monthly_expenses = 3000;
    financialHealthCheckRequest.ratio_targets = {
        "liquidity_ratio_expenses": 2.5,
        "liquidity_ratio_liabilities": 0.1,
        "current_ratio": 0.5,
        "asset_allocation_ratio": 1.5,
        "savings_ratio_gross": 0.1,
        "savings_ratio_net": 0.1
    };
    api.financialHealthCheck(financialHealthCheckRequest, callback)

ARGUMENTS

Parameter Description
liquid_assets
float
Value for the sum of cash and cash equivalents, checking accounts, savings accounts, money market accounts, money market mutual funds, CDs with short maturities, and similar assets.
non_liquid_assets
float
Value for non-money market investment accounts, vehicles, real estate, business interests, personal property, the cash value of insurance policies, and similar assets.
short_term_liabilities
float
Value for all debt and credit obligations, charges, bills, and payments due within one year.
total_liabilities
float
Value for total liabilities, examples include mortgages, car loans, credit card balances, and student loans. Includes short_term_liabilities.
gross_annual_income
float
Total amount of income earned annually before taxes.
net_monthly_income
float
Take-home monthly pay after taxes and other payroll deductions.
monthly_expenses
float
Value for average monthly living expenses.
ratio_targets
map
Target values for each of the available financial ratios. These values are used as a benchmark for the financial health check and determine pass or fail. More information for these ratios can be found in the Appendix.
      liquidity_ratio_expenses
      float
Target ratio value for liquidity_ratio_expenses. Defaults to 2.5. The ratio value is calculated as liquid_assets / monthly_expenses.
      liquidity_ratio_liabilities
      float
Target ratio value for liquidity_ratio_liabilities. Defaults to 0.1. The ratio value is calculated as liquid_assets / total_liabilities.
      current_ratio
      float
Target ratio value for current_ratio. Defaults to 0.5. The ratio value is calculated as liquid_assets / short_term_liabilities.
      asset_allocation_ratio
      float
Target ratio value for asset_allocation_ratio. Defaults to 1.5. The ratio value is calculated as liquid_assets / net_worth.
      savings_ratio_gross
      float
Target ratio value for savings_ratio_gross. Defaults to 0.1. The ratio value is calculated as monthly_surplus / gross_monthly_income.
      savings_ratio_net
      float
Target ratio value for savings_ratio_net. Defaults to 0.1. The ratio value is calculated as monthly_surplus / net_monthly_income.
client_id
UUID
The ID of a Nucleus client used to derive one or more of the following based on the client’s financials: liquid_assets, non_liquid_assets, short_term_liabilities, total_liabilities, net_monthly_income, and monthly_expenses. If raw values for any of these optional parameters are not provided, we will use client_id to try to derive those values instead.
lookback_periods
integer
Number of monthly periods to analyze when deriving income and expense values using a client_id. Values are averaged across all periods. Defaults to 3.

Example Response

{
    "liquidity_ratio_expenses": {
        "ratio_result": 1.6667,
        "target_value": 2.5,
        "pass": false,
        "percentile_grade": 66
    },
    "liquidity_ratio_liabilities": {
        "ratio_result": 0.3571,
        "target_value": 0.1,
        "pass": true,
        "percentile_grade": 100
    },
    "current_ratio": {
        "ratio_result": 0.4545,
        "target_value": 0.5,
        "pass": false,
        "percentile_grade": 90
    },
    "asset_allocation_ratio": {
        "ratio_result": 5,
        "target_value": 1.5,
        "pass": true,
        "percentile_grade": 100
    },
    "savings_ratio_gross": {
        "ratio_result": 0.1,
        "target_value": 0.1,
        "pass": true,
        "percentile_grade": 100
    },
    "savings_ratio_net": {
        "ratio_result": 0.1429,
        "target_value": 0.1,
        "pass": true,
        "percentile_grade": 100
    },
    "total_assets": 15000,
    "net_worth": 1000,
    "gross_monthly_income": 5000,
    "monthly_surplus": 500
}

RESPONSE

Field Description
liquidity_ratio_expenses Ratio measuring available liquidity with respect to ongoing expenses.
      ratio_result
      
The ratio value, calculated as liquid_assets / monthly_expenses.
      target_value
      
The target ratio value, as determined by ratio_targets.
      pass
      
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding target_value, then pass is true.
      percentile_grade
      
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the corresponding target_value.
liquidity_ratio_liabilities Ratio measuring available liquidity with respect to liabilities.
      ratio_result
      
The ratio value, calculated as liquid_assets / total_liabilities.
      target_value
      
The target ratio value, as determined by ratio_targets.
      pass
      
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding target_value, then pass is true.
      percentile_grade
      
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the corresponding target_value.
current_ratio Ratio measuring available liquidity with respect to short-term liabilities.
      ratio_result
      
The ratio value, calculated as liquid_assets / short_term_liabilities.
      target_value
      
The target ratio value, as determined by ratio_targets.
      pass
      
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding target_value, then pass is true.
      percentile_grade
      
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the corresponding target_value.
asset_allocation_ratio Ratio measuring available liquidity with respect to net worth.
      ratio_result
      
The ratio value, calculated as liquid_assets / net_worth.
      target_value
      
The target ratio value, as determined by ratio_targets.
      pass
      
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding target_value, then pass is true.
      percentile_grade
      
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the corresponding target_value.
savings_ratio_gross Ratio measuring savings potential with respect to gross income.
      ratio_result
      
The ratio value, calculated as monthly_surplus / gross_monthly_income.
      target_value
      
The target ratio value, as determined by ratio_targets.
      pass
      
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding target_value, then pass is true.
      percentile_grade
      
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the corresponding target_value.
savings_ratio_net Ratio measuring savings potential with respect to net income.
      ratio_result
      
The ratio value, calculated as monthly_surplus / net_monthly_income.
      target_value
      
The target ratio value, as determined by ratio_targets.
      pass
      
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding target_value, then pass is true.
      percentile_grade
      
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the corresponding target_value.
total_assets Total assets, calculated as liquid_assets + non_liquid_assets.
net_worth Net worth, calculated as total_assets - total_liabilities.
gross_monthly_income Gross monthly income, calculated as gross_annual_income / 12.
monthly_surplus Net monthly surplus, calculated as net_monthly_income - monthly_expenses.

NUCLEUS DATA DEPENDENCIES

Life Insurance Needs Calculator

When deciding to purchase life insurance, users face a common question: how much life insurance do I need? While some in the industry rely on broad rules of thumb (such as a multiple of household income), this calculator uses a discounted cash flow approach. Once the user provides expense and other pertinent information, the calculator returns the life insurance need, a breakdown of expenses by category, and return details broken down by period.

HTTP REQUEST

POST /life_insurance/needs_calculator

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "mortgage_balance": 200000,
        "other_debt": 100000,
        "interest_rate": 0.06,
        "end_of_life_expenses": 10000,
        "existing_life_insurance": 50000,
        "liquid_assets": 400000,
        "general_inflation_rate": 0.02,
        "education_inflation_rate": 0.05,
        "tax_rate": 0.25,
        "benefit_amount_rounding": 6,
        "margin_of_error": 0.05,
        "children_education_config":
        [
          {
            "current_age": 17,
            "education_config":
            [
              {
                "start_age": 18,
                "end_age": 22,
                "total_annual_cost": 40000
              }
            ]
          }
        ],
        "income_config":
        [
          {
            "annual_net_take_home_pay": 50000,
            "percentage_of_income_covered": 1,
            "income_benefit_duration": 5
          }
        ],
        "beneficiary_bequest_config":
        [
          {
            "years_until_bequest": 1,
            "bequest_amount": 10000,
            "bequest_duration": 5
          }
        ]
  }' "https://api.hydrogenplatform.com/proton/v1/life_insurance/needs_calculator"
LifeInsuranceApi lifeInsuranceApi = new LifeInsuranceApi();
LifeInsuranceNeedsCalculatorRequest lifeInsuranceNeedsCalculatorRequest = new
        LifeInsuranceNeedsCalculatorRequest();
lifeInsuranceNeedsCalculatorRequest.setMortgageBalance(BigDecimal.valueOf(200000));
lifeInsuranceNeedsCalculatorRequest.setOtherDebt(BigDecimal.valueOf(10000));
lifeInsuranceNeedsCalculatorRequest.setInterestRate(0.06F);
lifeInsuranceNeedsCalculatorRequest.setEndOfLifeExpenses(BigDecimal.valueOf(10000));
lifeInsuranceNeedsCalculatorRequest.setExistingLifeInsurance(BigDecimal.valueOf(50000));
lifeInsuranceNeedsCalculatorRequest.setLiquidAssets(BigDecimal.valueOf(40000));
lifeInsuranceNeedsCalculatorRequest.setGeneralInflationRate(0.02F);
lifeInsuranceNeedsCalculatorRequest.setEducationInflationRate(0.05F);
lifeInsuranceNeedsCalculatorRequest.setTaxRate(0.25F);
lifeInsuranceNeedsCalculatorRequest.setBenefitAmountRounding(6);
lifeInsuranceNeedsCalculatorRequest.setMarginOfError(0.05F);
ChildrenEducationConfig childrenEducationConfig = new ChildrenEducationConfig();
childrenEducationConfig.setCurrentAge(17);
EducationConfig educationConfig = new EducationConfig();
educationConfig.setStartAge(18);
educationConfig.setEndAge(22);
educationConfig.setTotalAnnualCost(BigDecimal.valueOf(40000));
childrenEducationConfig.setEducationConfig(Arrays.asList(educationConfig));
lifeInsuranceNeedsCalculatorRequest.setChildrenEducationConfig(Arrays.asList(
        childrenEducationConfig
));
IncomeConfig incomeConfig = new IncomeConfig();
incomeConfig.setAnnualNetTakeHomePay(BigDecimal.valueOf(50000));
incomeConfig.setPercentageOfIncomeCovered(1F);
incomeConfig.setIncomeBenefitDuration(5);
lifeInsuranceNeedsCalculatorRequest.setIncomeConfig(Arrays.asList(incomeConfig));
BeneficiaryBequestConfig beneficiaryBequestConfig = new BeneficiaryBequestConfig();
beneficiaryBequestConfig.setYearsUntilBequest(1);
beneficiaryBequestConfig.setBequestAmount(BigDecimal.valueOf(100000));
beneficiaryBequestConfig.setBequestDuration(5);
lifeInsuranceNeedsCalculatorRequest.setBeneficiaryBequestConfig(Arrays.asList(beneficiaryBequestConfig));
Map<String, Object> lifeInsuranceNeedsCalculatorResponse =
        lifeInsuranceApi.lifeInsuranceNeedsCalculator(lifeInsuranceNeedsCalculatorRequest);
System.out.println(lifeInsuranceNeedsCalculatorResponse);
api_instance = proton_api.LifeInsuranceApi(proton_api.ApiClient(configuration))
life_insurance_needs_calculator_request = proton_api.LifeInsuranceNeedsCalculatorRequest(
    mortgage_balance=20000, other_debt=10000, interest_rate=0.06, end_of_life_expenses=10000, existing_life_insurance=5000,
    liquid_assets=40000, general_inflation_rate=0.02, education_inflation_rate=0.05, tax_rate=0.25, benefit_amount_rounding=6,
    margin_of_error=0.05, children_education_config=[
        proton_api.ChildrenEducationConfig(
            current_age=17, education_config=[proton_api.EducationConfig(
                start_age=18, end_age=22, total_annual_cost=40000
            )]
        )
    ], income_config=[proton_api.IncomeConfig(annual_net_take_home_pay=50000, percentage_of_income_covered=1, income_benefit_duration=5)],
    beneficiary_bequest_config=[proton_api.BeneficiaryBequestConfig(
        years_until_bequest=1, bequest_amount=10000, bequest_duration=5
    )]
)
try:
    # LifeInsuranceApi - Life Insurance Needs Calculator
    api_response = api_instance.life_insurance_needs_calculator(life_insurance_needs_calculator_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling GoalApi->life_insurance_needs_calculator: %s\n" % e)
api_instance = ProtonApi::LifeInsuranceApi.new
lifeInsuranceNeedsCalculatorRequest = ProtonApi::LifeInsuranceNeedsCalculatorRequest.new
begin
  lifeInsuranceNeedsCalculatorRequest.mortgage_balance = 20000
  lifeInsuranceNeedsCalculatorRequest.other_debt = 10000
  lifeInsuranceNeedsCalculatorRequest.interest_rate = 0.06
  lifeInsuranceNeedsCalculatorRequest.end_of_life_expenses = 10000
  lifeInsuranceNeedsCalculatorRequest.existing_life_insurance = 5000
  lifeInsuranceNeedsCalculatorRequest.liquid_assets = 40000
  lifeInsuranceNeedsCalculatorRequest.general_inflation_rate = 0.02
  lifeInsuranceNeedsCalculatorRequest.education_inflation_rate = 0.05
  lifeInsuranceNeedsCalculatorRequest.tax_rate = 0.25
  lifeInsuranceNeedsCalculatorRequest.benefit_amount_rounding = 6
  lifeInsuranceNeedsCalculatorRequest.margin_of_error = 0.05
  childrenEducationConfig = ProtonApi::ChildrenEducationConfig.new
  childrenEducationConfig.current_age = 17
  educationConfig = ProtonApi::EducationConfig.new
  educationConfig.start_age = 18
  educationConfig.end_age = 22
  educationConfig.total_annual_cost = 40000
  childrenEducationConfig.education_config =[educationConfig]
  lifeInsuranceNeedsCalculatorRequest.children_education_config = [childrenEducationConfig]
  incomeConfig = ProtonApi::IncomeConfig.new
  incomeConfig.annual_net_take_home_pay = 50000
  incomeConfig.percentage_of_income_covered = 1
  incomeConfig.income_benefit_duration = 5
  lifeInsuranceNeedsCalculatorRequest.income_config = [incomeConfig]
  beneficiaryBequestConfig = ProtonApi::BeneficiaryBequestConfig.new
  beneficiaryBequestConfig.years_until_bequest = 1
  beneficiaryBequestConfig.bequest_amount = 10000
  beneficiaryBequestConfig.bequest_duration = 5
  lifeInsuranceNeedsCalculatorRequest.beneficiary_bequest_config = [beneficiaryBequestConfig]
  lifeInsuranceNeedsCalculatorResponse = api_instance
                                             .life_insurance_needs_calculator(lifeInsuranceNeedsCalculatorRequest)
  p lifeInsuranceNeedsCalculatorResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling life_insurance_needs_calculator_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\LifeInsuranceApi(
    new GuzzleHttp\Client(),
    $config
);
$lifeInsuranceNeedsCalculatorRequest = new com\hydrogen\proton\Model\LifeInsuranceNeedsCalculatorRequest();
try {

    $lifeInsuranceNeedsCalculatorRequest->setMortgageBalance(200000);
    $lifeInsuranceNeedsCalculatorRequest->setOtherDebt(10000);
    $lifeInsuranceNeedsCalculatorRequest->setInterestRate(0.06);
    $lifeInsuranceNeedsCalculatorRequest->setEndOfLifeExpenses(10000);
    $lifeInsuranceNeedsCalculatorRequest->setExistingLifeInsurance(50000);
    $lifeInsuranceNeedsCalculatorRequest->setLiquidAssets(400000);
    $lifeInsuranceNeedsCalculatorRequest->setGeneralInflationRate(0.02);
    $lifeInsuranceNeedsCalculatorRequest->setEducationInflationRate(0.05);
    $lifeInsuranceNeedsCalculatorRequest->setTaxRate(0.25);
    $lifeInsuranceNeedsCalculatorRequest->setBenefitAmountRounding(6);
    $lifeInsuranceNeedsCalculatorRequest->setMarginOfError(0.05);

    $childrenEducationConfig = new \com\hydrogen\proton\Model\ChildrenEducationConfig();
    $childrenEducationConfig->setCurrentAge(17);
    $educationConfig = new \com\hydrogen\proton\Model\EducationConfig();
    $educationConfig->setStartAge(18);
    $educationConfig->setEndAge(22);
    $educationConfig->setTotalAnnualCost(4000);
    $childrenEducationConfig->setEducationConfig(array($educationConfig));
    $lifeInsuranceNeedsCalculatorRequest->setChildrenEducationConfig(array($childrenEducationConfig));

    $incomeConfig = new \com\hydrogen\proton\Model\IncomeConfig();
    $incomeConfig->setAnnualNetTakeHomePay(50000);
    $incomeConfig->setPercentageOfIncomeCovered(1);
    $incomeConfig->setIncomeBenefitDuration(5);
    $lifeInsuranceNeedsCalculatorRequest->setIncomeConfig(array($incomeConfig));


    $beneficiaryRequestConfig = new \com\hydrogen\proton\Model\BeneficiaryBequestConfig();
    $beneficiaryRequestConfig->setYearsUntilBequest(1);
    $beneficiaryRequestConfig->setBequestAmount(100000);
    $beneficiaryRequestConfig->setBequestDuration(5);
    $lifeInsuranceNeedsCalculatorRequest->setBeneficiaryBequestConfig(array($beneficiaryRequestConfig));
    $result = $apiInstance->lifeInsuranceNeedsCalculator($lifeInsuranceNeedsCalculatorRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling LifeInsuranceApi->lifeInsuranceNeedsCalculator: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.LifeInsuranceApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
    var api = new HydrogenProtonApi.LifeInsuranceApi();
    var lifeInsuranceNeedsCalculatorRequest = new HydrogenProtonApi.LifeInsuranceNeedsCalculatorRequest();
    lifeInsuranceNeedsCalculatorRequest.mortgage_balance =200000;
    lifeInsuranceNeedsCalculatorRequest.other_debt=100000;
    lifeInsuranceNeedsCalculatorRequest.interest_rate=0.06;
    lifeInsuranceNeedsCalculatorRequest.end_of_life_expenses=10000;
    lifeInsuranceNeedsCalculatorRequest.existing_life_insurance=50000;
    lifeInsuranceNeedsCalculatorRequest.liquid_assets=400000;
    lifeInsuranceNeedsCalculatorRequest.general_inflation_rate=0.02;
    lifeInsuranceNeedsCalculatorRequest.education_inflation_rate=0.05;
    lifeInsuranceNeedsCalculatorRequest.tax_rate=0.25;
    lifeInsuranceNeedsCalculatorRequest.benefit_amount_rounding=6;
    lifeInsuranceNeedsCalculatorRequest.margin_of_error=0.05;
    lifeInsuranceNeedsCalculatorRequest.children_education_config= [
        {
            "current_age": 17,
            "education_config":
                [
                    {
                        "start_age": 18,
                        "end_age": 22,
                        "total_annual_cost": 40000
                    }
                ]
        }
    ];
    lifeInsuranceNeedsCalculatorRequest.income_config =[
        {
            "annual_net_take_home_pay": 50000,
            "percentage_of_income_covered": 1,
            "income_benefit_duration": 5
        }
    ];
    lifeInsuranceNeedsCalculatorRequest.beneficiary_bequest_config= [
        {
            "years_until_bequest": 1,
            "bequest_amount": 10000,
            "bequest_duration": 5
        }

    ];

    api.lifeInsuranceNeedsCalculator(lifeInsuranceNeedsCalculatorRequest, callback)

ARGUMENTS

Parameter Description
mortgage_balance
float, conditioanl requirement
The user’s outstanding mortgage balance.
other_debt
integer, conditional requirement
Other outstanding debt.
interest_rate
float, required
The annual interest rate earned once the benefit amount is received.
end_of_life_expenses
float
Burial, funeral, and other end-of-life expenses to be paid at the first period. If excluded, defaults to 0.
existing_life_insurance
float
Existing life insurance currently held by the insuree. If excluded, defaults to 0.
liquid_assets
float
Current liquid assets owned by the insuree and beneficiary. If excluded, defaults to 0.
general_inflation_rate
float
The inflation rate to be applied to the benefit_amount and annual_net_take_home_pay. If excluded, defaults to 0.
education_inflation_rate
float
The inflation rate to be applied to all tuition. If excluded, defaults to 0.
tax_rate
float
The tax rate to be applied to investment earnings from the interest_rate. Life insurance benefits are assumed to be tax-free. If excluded, defaults to 0.
benefit_amount_rounding
integer
A parameter to round the benefit amount up to a configurable number of digits. This parameter should be utilized if a firm will not underwrite exact life insurance amounts, but will round to the nearest amount. 0: round to the hundredth, 1: round to the tenth, 2: round to a single digit, 3: round to two digits, etc. If excluded, defaults to 0.
margin_of_error
float
The margin of error to apply to the life insurance needed, before rounding. A margin_of_error of 0.10 would return 110% of the total insurance needed. If excluded, defaults to 0.
children_education_config
map
Benefit information to provide for a child’s primary, secondary and college education.
      current_age
      integer, required
The child’s age as of the first period.
      education_config
      map, required
A configuration of the child’s education cost.
            start_age
            integer, required
The child’s age at the beginning of the first education year.
            end_age
            integer, required
The child’s age at the beginning of the last education year.
            total_annual_cost
            float, required
The total annual cost of the child’s education.
income_config
map
Information on replacement income for beneficiaries. Income is assumed to increase with the rate of inflation.
      annual_net_take_home_pay
      float, required
The policy owner’s annual after-tax income.
      percentage_of_income_covered
      float
The percentage of annual_net_take_home_pay needed by beneficiaries. If excluded, defaults to 1.
      income_benefit_duration
      integer
The number of years needed to provide replacement income to beneficiaries, starting at the first period. If excluded, defaults to 10.
beneficiary_bequest_config
map
Information on additional benefits needed by beneficiaries.
      bequest_amount
      float, required
The amount of the benefit, paid annually.
      years_until_bequest
      integer
The number of years until the benefit is needed. A value of 0 indicates the benefit would be needed immediately (the first period). If excluded, defaults to 0.
      bequest_duration
      integer
The amount of years to repeat the benefit_amount. If excluded, defaults to 10.
client_id
UUID, conditional requirement
The ID of a Nucleus client used to derive one or more of the following based on the client’s financials: mortgage_balance, other_debt, and liquid_assets. If required parameters mortgage_balance and/or other_debt are not provided, client_id is required. If a raw value for optional parameter liquid_assets is not provided, we will use client_id to try to derive this value instead.

Example Response

{
    "life_insurance_needed": 390000,
    "total_life_insurance_needed": 440000,
    "life_insurance_needs_breakdown": {
        "mortgage": 200000,
        "other": 100000,
        "education": 213033.65,
        "income_replacement": 243087.46,
        "beneficiary_bequest": 47454.39,
        "end_of_life": 10000
    },
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 840000
        },
        "1": {
            "period_earnings": 0,
            "period_withdrawal": 361000,
            "cumulative_earnings": 0,
            "cumulative_withdrawals": 361000,
            "ending_balance": 479000
        },
        "2": {
            "period_earnings": 21555,
            "period_withdrawal": 106524,
            "cumulative_earnings": 21555,
            "cumulative_withdrawals": 467524,
            "ending_balance": 394031
        },
        "3": {
            "period_earnings": 17731.39,
            "period_withdrawal": 109977.48,
            "cumulative_earnings": 39286.39,
            "cumulative_withdrawals": 577501.48,
            "ending_balance": 301784.91
        },
        "4": {
            "period_earnings": 13580.32,
            "period_withdrawal": 113566.18,
            "cumulative_earnings": 52866.72,
            "cumulative_withdrawals": 691067.66,
            "ending_balance": 201799.06
        },
        "5": {
            "period_earnings": 9080.96,
            "period_withdrawal": 117296.11,
            "cumulative_earnings": 61947.67,
            "cumulative_withdrawals": 808363.77,
            "ending_balance": 93583.9
        },
        "6": {
            "period_earnings": 4211.28,
            "period_withdrawal": 64865.45,
            "cumulative_earnings": 66158.95,
            "cumulative_withdrawals": 873229.22,
            "ending_balance": 32929.73
        }
    }
}

RESPONSE

Field Description
life_insurance_needed The supplemental life insurance needed by the user.
total_life_insurance_needed The total life insurance needed by the user, including the current life insurance.
life_insurance_needs_breakdown A breakdown of what the life insurance proceeds will be used for.
      mortgage
      
Insurance required to cover existing mortgage balance, paid immediately.
      other
      
Insurance required to cover other debt.
      education
      
Insurance required to cover future education expenses.
      income_replacement
      
Insurance required to cover loss of income.
      beneficiary_bequest
      
Insurance required to cover amount being bequested.
      end_of_life
      
Insurance required to cover end of life expenses.
return_details Portfolio return information over the length of the horizon, broken down by period. Period 0 represents the assets available including the calculated insurance payment. Period 1 reflects any immediate expenses, and the remaining balance is drawn down starting with period 2 to cover ongoing expenses.
      period_earnings
      
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      period_withdrawal
      
The withdrawal made for this period.
      cumulative_earnings
      
The cumulative investment earnings made up to and including this period.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Major Purchase Calculator

When planning to make a major purchase, such as a down payment on a home/car, investors need to determine how much is needed and how to stay on track. After collecting information about the user’s major purchase, this tool solves for three different parameters: deposit amount, purchase amount, and purchase horizon.

Deposit Amount

A calculator to help determine the deposit amount needed to meet the major purchase goal.

HTTP REQUEST

POST /purchase_calculator/deposit_amount

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "purchase_horizon": 5,
        "purchase_amount": 50000,
        "portfolio_return": 0.06,
        "horizon_frequency_interval": "year",
        "current_savings": 0,
        "deposit_schedule": {
            "deposit_frequency_interval": "year",
            "adjust_deposit_for_inflation": true
        },
        "inflation_rate": 0.02,
        "investment_tax": 0.25
    }' "https://api.hydrogenplatform.com/proton/v1/purchase_calculator/deposit_amount"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
PurchaseCalculatorDepositAmountRequest purchaseCalculatorDepositAmountRequest =
        new PurchaseCalculatorDepositAmountRequest();
purchaseCalculatorDepositAmountRequest.setPurchaseHorizon(5);
purchaseCalculatorDepositAmountRequest.setPurchaseAmount(5000F);
purchaseCalculatorDepositAmountRequest.setPortfolioReturn(0.06F);
purchaseCalculatorDepositAmountRequest.setHorizonFrequencyInterval(PurchaseCalculatorDepositAmountRequest.HorizonFrequencyIntervalEnum.YEAR);
purchaseCalculatorDepositAmountRequest.setCurrentSavings(1000F);
purchaseCalculatorDepositAmountRequest.setInflationRate(0.02F);
purchaseCalculatorDepositAmountRequest.setInvestmentTax(0.25F);
CalculatorDepositSchedule calculatorDepositSchedule = new CalculatorDepositSchedule();
calculatorDepositSchedule.setAdjustDepositForInflation(Boolean.TRUE);
calculatorDepositSchedule.setDepositFrequencyInterval(CalculatorDepositSchedule.DepositFrequencyIntervalEnum.YEAR);
purchaseCalculatorDepositAmountRequest.setDepositSchedule(calculatorDepositSchedule);
Map<String, Object> purchaseCalculatorDepositAmountResponse =
        financialPlanningApi.purchaseCalculatorDepositAmount(purchaseCalculatorDepositAmountRequest);
System.out.println(purchaseCalculatorDepositAmountResponse);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
purchase_calculator_deposit_amount = proton_api.PurchaseCalculatorDepositAmountRequest(
    purchase_horizon=5, purchase_amount=5000, portfolio_return=0.06, horizon_frequency_interval='year', current_savings=1000, inflation_rate=0.02,
    investment_tax=.25, deposit_schedule=proton_api.CalculatorDepositSchedule(
        adjust_deposit_for_inflation=True, deposit_frequency_interval='year',
    )
)
try:
    # Financial Planning - Purchase Calculator Deposit Amount
    api_response = api_instance.purchase_calculator_deposit_amount(purchase_calculator_deposit_amount)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->purchase_calculator_deposit_amount: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
purchaseCalculatorDepositAmountRequest = ProtonApi::PurchaseCalculatorDepositAmountRequest.new
calculatorDepositSchedule = ProtonApi::CalculatorDepositSchedule.new
begin
  purchaseCalculatorDepositAmountRequest.purchase_amount = 50000
  purchaseCalculatorDepositAmountRequest.purchase_horizon = 5
  purchaseCalculatorDepositAmountRequest.portfolio_return = 0.06
  purchaseCalculatorDepositAmountRequest.current_savings = 1000
  purchaseCalculatorDepositAmountRequest.horizon_frequency_interval = 'year'
  calculatorDepositSchedule.adjust_deposit_for_inflation = true
  calculatorDepositSchedule.deposit_frequency_interval = 'year'
  purchaseCalculatorDepositAmountRequest.deposit_schedule = calculatorDepositSchedule
  purchaseCalculatorDepositAmountRequest.inflation_rate = 0.02
  purchaseCalculatorDepositAmountRequest.investment_tax = 0.25
  purchase_deposit_response = api_instance.purchase_calculator_deposit_amount(purchaseCalculatorDepositAmountRequest)
  p purchase_deposit_response
rescue ProtonApi::ApiError => e
  puts "Exception when calling purchase_calculator_deposit_amount_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$purchaseCalculatorDepositAmountRequest = new com\hydrogen\proton\Model\PurchaseCalculatorDepositAmountRequest();
try {

    $purchaseCalculatorDepositAmountRequest->setPurchaseHorizon(5);
    $purchaseCalculatorDepositAmountRequest->setPurchaseAmount(50000);
    $purchaseCalculatorDepositAmountRequest->setPortfolioReturn(0.06);
    $purchaseCalculatorDepositAmountRequest->setHorizonFrequencyInterval(year);
    $purchaseCalculatorDepositAmountRequest->setCurrentSavings(1000);
    $depositScheduleCalculatorDeposit = new \com\hydrogen\proton\Model\CalculatorDepositSchedule();
    $depositScheduleCalculatorDeposit->setDepositFrequencyInterval('year');
    $depositScheduleCalculatorDeposit->setAdjustDepositForInflation(true);
    $purchaseCalculatorDepositAmountRequest->setDepositSchedule(($depositScheduleCalculatorDeposit));
    $purchaseCalculatorDepositAmountRequest->setInflationRate(0.02);
    $purchaseCalculatorDepositAmountRequest->setInvestmentTax(0.25);
    $result = $apiInstance->purchaseCalculatorDepositAmount($purchaseCalculatorDepositAmountRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->purchaseCalculatorDepositAmount: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
    var purchaseCalculatorDepositAmountRequest = new HydrogenProtonApi.PurchaseCalculatorDepositAmountRequest();
    purchaseCalculatorDepositAmountRequest.purchase_horizon=5;
    purchaseCalculatorDepositAmountRequest.purchase_amount=50000;
    purchaseCalculatorDepositAmountRequest.portfolio_return=0.06;
    purchaseCalculatorDepositAmountRequest.horizon_frequency_interval="year";
    purchaseCalculatorDepositAmountRequest.current_savings=1000;
    purchaseCalculatorDepositAmountRequest.deposit_schedule= {

        "deposit_frequency_interval": "year",
        "adjust_deposit_for_inflation": true
    },
        purchaseCalculatorDepositAmountRequest.inflation_rate=0.02;
    purchaseCalculatorDepositAmountRequest.investment_tax=0.25;
    api.purchaseCalculatorDepositAmount(purchaseCalculatorDepositAmountRequest, callback);

ARGUMENTS

Parameter Description
purchase_horizon
integer, required
The amount of time until the major purchase is made.
purchase_amount
float, required
The amount of the major purchase.
portfolio_return
float, required
The portfolio’s return, calculated on an annual basis.
horizon_frequency_interval
string
The interval at which to measure the purchase horizon. The value may be one of the following: year, quarter, month, or week. Earnings are calculated at the same frequency as horizon_frequency_interval. If excluded, defaults to year.
current_savings
float
The current amount of savings earmarked for the goal. If excluded, defaults to 0.
deposit_schedule
map
The deposit schedule for the major purchase goal.
      deposit_frequency_interval
      string
The period interval to be used in relation to the deposit_amount. The value may be one of the following: year, quarter, month, or week. If excluded, defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposits are increased over time with the rate of inflation. If excluded, defaults to true.
inflation_rate
float
The annual inflation rate of the purchase_amount. If excluded, defaults to 0.
investment_tax
float
The tax on the investments used to pay for the major purchase. If excluded, defaults to 0.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive current_savings. If current_savings is not provided, we will try to use account_ids to derive this value instead.

Example Response

{
    "deposit_amount": 12574.34,
    "deposit_frequency_interval": "year",
    "adjusted_goal_amount": 73605.39,
    "projected_savings_at_purchase_horizon": 73605.39,
    "total_earnings": 8168.03,
    "total_contributions": 65437.36,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "ending_balance": 0
        },
        "1": {
            "period_earnings": 0,
            "period_contribution": 12574.34,
            "cumulative_earnings": 0,
            "cumulative_contributions": 12574.34,
            "ending_balance": 12574.34
        },
        "2": {
            "period_earnings": 754.46,
            "period_contribution": 12825.82,
            "cumulative_earnings": 754.46,
            "cumulative_contributions": 25400.16,
            "ending_balance": 26154.62
        },
        "3": {
            "period_earnings": 1569.28,
            "period_contribution": 13082.34,
            "cumulative_earnings": 2323.74,
            "cumulative_contributions": 38482.5,
            "ending_balance": 40806.24
        },
        "4": {
            "period_earnings": 2448.37,
            "period_contribution": 13343.99,
            "cumulative_earnings": 4772.11,
            "cumulative_contributions": 51826.49,
            "ending_balance": 56598.6
        },
        "5": {
            "period_earnings": 3395.92,
            "period_contribution": 13610.87,
            "cumulative_earnings": 8168.03,
            "cumulative_contributions": 65437.36,
            "ending_balance": 73605.39
        }
    }
}

RESPONSE

Field Description
deposit_amount The amount to deposit in order to meet the purchase goal.
deposit_frequency_interval The frequency interval of the deposit.
adjusted_goal_amount The effective goal target amount, adjusted for taxes and inflation.
projected_savings_at_purchase_horizon The total amount of savings that are projected to be available at the final horizon, expressed in today’s dollars.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made.
      period_contribution
      
The deposit made for this period.
      cumulative_earnings
      
The cumulative investment earnings made up to and including this period.
      cumulative_contributions
      
The cumulative deposits made up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Purchase Amount

A calculator to help determine the amount that the user could afford for the major purchase, given the other inputs.

HTTP REQUEST

POST /purchase_calculator/amount

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "purchase_horizon": 6,
        "portfolio_return": 0.06,
        "horizon_frequency_interval": "year",
        "current_savings": 0,
        "deposit_schedule": {
            "deposit_amount": 10000,
            "deposit_frequency_interval": "year",
            "adjust_deposit_for_inflation": true
        },
        "inflation_rate": 0.01,
        "investment_tax": 0.2
    }' "https://api.hydrogenplatform.com/proton/v1/purchase_calculator/amount"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
PurchaseCalculatorAmountRequest purchaseCalculatorAmountRequest =  new PurchaseCalculatorAmountRequest();
purchaseCalculatorAmountRequest.setPurchaseHorizon(5);
purchaseCalculatorAmountRequest.setPortfolioReturn(0.06F);
purchaseCalculatorAmountRequest.setHorizonFrequencyInterval(PurchaseCalculatorAmountRequest.HorizonFrequencyIntervalEnum.YEAR);
purchaseCalculatorAmountRequest.setCurrentSavings(1000F);
purchaseCalculatorAmountRequest.setInflationRate(0.02F);
purchaseCalculatorAmountRequest.setInvestmentTax(0.25F);
CalculatorDepositSchedule1 calculatorDepositSchedule11 = new CalculatorDepositSchedule1();
calculatorDepositSchedule11.setDepositAmount(10000F);
calculatorDepositSchedule11.setAdjustDepositForInflation(true);
calculatorDepositSchedule11.setDepositFrequencyInterval(CalculatorDepositSchedule1.DepositFrequencyIntervalEnum.YEAR);
purchaseCalculatorAmountRequest.setDepositSchedule(calculatorDepositSchedule11);
Map<String, Object> purchaseCalculatorAmountResponse =
        financialPlanningApi.purchaseCalculatorAmount(purchaseCalculatorAmountRequest);
System.out.println(
        purchaseCalculatorAmountResponse
);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
purchase_calculator_amount_request = proton_api.PurchaseCalculatorAmountRequest(
    purchase_horizon=5, portfolio_return=0.06, horizon_frequency_interval='year', current_savings=1000, inflation_rate=0.02,
    investment_tax=0.25, deposit_schedule=proton_api.CalculatorDepositSchedule1(
        deposit_amount=10000, adjust_deposit_for_inflation=True, deposit_frequency_interval='year'
    )
)
try:
    # Financial Planning - Purchase Calculator Amount
    api_response = api_instance.purchase_calculator_amount(purchase_calculator_amount_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->purchase_calculator_amount: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
purchaseCalculatorAmountRequest = ProtonApi::PurchaseCalculatorAmountRequest.new
begin
  purchaseCalculatorAmountRequest.purchase_horizon = 5
  purchaseCalculatorAmountRequest.portfolio_return = 0.06
  purchaseCalculatorAmountRequest.horizon_frequency_interval = "year"
  purchaseCalculatorAmountRequest.current_savings = 1000
  calculatorDepositSchedule = ProtonApi::CalculatorDepositSchedule1.new
  calculatorDepositSchedule.deposit_amount = 10000
  calculatorDepositSchedule.deposit_frequency_interval = 'year'
  calculatorDepositSchedule.adjust_deposit_for_inflation = true
  purchaseCalculatorAmountRequest.deposit_schedule = calculatorDepositSchedule
  purchaseCalculatorAmountRequest.inflation_rate = 0.02
  purchaseCalculatorAmountRequest.investment_tax = 0.25
  purchaseCalculatorAmountResponse = api_instance.purchase_calculator_amount(purchaseCalculatorAmountRequest)
  p purchaseCalculatorAmountResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling purchase_calculator_amount_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$purchaseCalculatorAmountRequest = new com\hydrogen\proton\Model\PurchaseCalculatorAmountRequest();
try {

    $purchaseCalculatorAmountRequest->setPurchaseHorizon(5);
    $purchaseCalculatorAmountRequest->setPortfolioReturn(0.06);
    $purchaseCalculatorAmountRequest->setHorizonFrequencyInterval(year);
    $purchaseCalculatorAmountRequest->setCurrentSavings(1000);
    $depositSchedulePurchaseCalculator = new \com\hydrogen\proton\Model\CalculatorDepositSchedule1();
    $depositSchedulePurchaseCalculator->setDepositAmount(1000);
    $depositSchedulePurchaseCalculator->setDepositFrequencyInterval('year');
    $depositSchedulePurchaseCalculator->setAdjustDepositForInflation(true);
    $purchaseCalculatorAmountRequest->setDepositSchedule($depositSchedulePurchaseCalculator);
    $purchaseCalculatorAmountRequest->setInflationRate(0.02);
    $purchaseCalculatorAmountRequest->setInvestmentTax(0.25);
    $result = $apiInstance->purchaseCalculatorAmount($purchaseCalculatorAmountRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->purchaseCalculatorAmount: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
    var api = new HydrogenProtonApi.FinancialPlanningApi();
    var purchaseCalculatorAmountRequest = new HydrogenProtonApi.PurchaseCalculatorAmountRequest();
    purchaseCalculatorAmountRequest.purchase_horizon=5;
    purchaseCalculatorAmountRequest.portfolio_return=0.06;
    purchaseCalculatorAmountRequest.horizon_frequency_interval="year";
    purchaseCalculatorAmountRequest.current_savings=1000;
    purchaseCalculatorAmountRequest.deposit_schedule= {
        "deposit_amount": 10000,
        "deposit_frequency_interval": "year",
        "adjust_deposit_for_inflation": true
    },
        purchaseCalculatorAmountRequest.inflation_rate=0.02;
    purchaseCalculatorAmountRequest.investment_tax=0.25;
    api.purchaseCalculatorAmount(purchaseCalculatorAmountRequest, callback)

ARGUMENTS

Parameter Description
purchase_horizon
integer, required
The amount of time until the major purchase is made.
portfolio_return
float, required
The portfolio’s return, calculated on an annual basis.
horizon_frequency_interval
string
The interval at which to measure the purchase_horizon. The value may be one of the following: year, quarter, month, or week. Earnings are calculated at the same frequency as horizon_frequency_interval. If excluded, defaults to year.
current_savings
float
The current amount of savings earmarked for the goal. If excluded, defaults to 0.
deposit_schedule
map
The deposit schedule for the major purchase goal.
      deposit_amount
      float
The periodic additions to the major purchase goal. If excluded, defaults to 0.
      deposit_frequency_interval
      string
The period interval to be used in relation to the deposit_amount. The value may be one of the following: year, quarter, month, or week. If excluded, defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposits are increased over time with the rate of inflation. If excluded, defaults to true.
inflation_rate
float
The annual inflation rate of the purchase_amount. If excluded, defaults to 0.
investment_tax
float
The tax on the investments used to pay for the major purchase. If excluded, defaults to 0.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive current_savings. If current_savings is not provided, we will try to use account_ids to derive this value instead.

Example Response

{
    "purchase_amount": 57119.83,
    "purchase_amount_adjusted": 53809.47,
    "projected_savings_at_purchase_horizon": 71399.79,
    "total_earnings": 9879.64,
    "total_contributions": 61520.15,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "ending_balance": 0
        },
        "1": {
            "period_earnings": 0,
            "period_contribution": 10000,
            "cumulative_earnings": 0,
            "cumulative_contributions": 10000,
            "ending_balance": 10000
        },
        "2": {
            "period_earnings": 600,
            "period_contribution": 10100,
            "cumulative_earnings": 600,
            "cumulative_contributions": 20100,
            "ending_balance": 20700
        },
        "3": {
            "period_earnings": 1242,
            "period_contribution": 10201,
            "cumulative_earnings": 1842,
            "cumulative_contributions": 30301,
            "ending_balance": 32143
        },
        "4": {
            "period_earnings": 1928.58,
            "period_contribution": 10303.01,
            "cumulative_earnings": 3770.58,
            "cumulative_contributions": 40604.01,
            "ending_balance": 44374.59
        },
        "5": {
            "period_earnings": 2662.48,
            "period_contribution": 10406.04,
            "cumulative_earnings": 6433.06,
            "cumulative_contributions": 51010.05,
            "ending_balance": 57443.11
        },
        "6": {
            "period_earnings": 3446.59,
            "period_contribution": 10510.1,
            "cumulative_earnings": 9879.64,
            "cumulative_contributions": 61520.15,
            "ending_balance": 71399.79
        }
    }
}

RESPONSE

Field Description
purchase_amount The amount of the major purchase.
purchase_amount_adjusted The amount of the major purchase, represented in today’s dollars.
projected_savings_at_purchase horizon The total amount of savings that are projected to be available at purchase_horizon, expressed in today’s dollars.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made.
      period_contribution
      
The deposit made for this period.
      cumulative_earnings
      
The cumulative earnings made up to and including this period.
      cumulative_contributions
      
The cumulative deposits made up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Purchase Horizon

A calculator to help determine the amount of years needed to save for a major purchase.

HTTP REQUEST

POST /purchase_calculator/horizon

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "purchase_amount": 50000,
        "portfolio_return": 0.06,
        "current_savings": 0,
        "deposit_schedule": {
            "deposit_amount": 10000,
            "deposit_frequency_interval": "year",
            "adjust_deposit_for_inflation": true
        },
        "inflation_rate": 0.02,
        "investment_tax": 0.25
    }' "https://api.hydrogenplatform.com/proton/v1/purchase_calculator/horizon"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
PurchaseCalculatorHorizonRequest purchaseCalculatorHorizonRequest = new PurchaseCalculatorHorizonRequest();
purchaseCalculatorHorizonRequest.setPurchaseAmount(5000F);
purchaseCalculatorHorizonRequest.setPortfolioReturn(0.06F);
purchaseCalculatorHorizonRequest.setCurrentSavings(1000F);
purchaseCalculatorHorizonRequest.setInflationRate(0.02F);
purchaseCalculatorHorizonRequest.setInvestmentTax(0.25F);
CalculatorDepositSchedule1 purchaseCalculatorDepositSchedule =  new CalculatorDepositSchedule1();
purchaseCalculatorDepositSchedule.setDepositAmount(1000F);
purchaseCalculatorDepositSchedule.setDepositFrequencyInterval(CalculatorDepositSchedule1.DepositFrequencyIntervalEnum.YEAR);
purchaseCalculatorDepositSchedule.setAdjustDepositForInflation(Boolean.TRUE);
purchaseCalculatorHorizonRequest.setDepositSchedule(purchaseCalculatorDepositSchedule);
Map<String, Object> purchaseCalculatorHorizonResponse =
        financialPlanningApi.purchaseCalculatorHorizon(purchaseCalculatorHorizonRequest);
System.out.println(purchaseCalculatorHorizonResponse);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
purchase_calculator_horizon = proton_api.PurchaseCalculatorHorizonRequest(
    purchase_amount=5000, portfolio_return=0.06, current_savings=100, inflation_rate=0.02, investment_tax=0.25, deposit_schedule=proton_api
    .CalculatorDepositSchedule1(deposit_amount=1000, deposit_frequency_interval='year', adjust_deposit_for_inflation=True)
)
try:
    # Financial Planning - Purchase Calculator Horizon
    api_response = api_instance.purchase_calculator_horizon(purchase_calculator_horizon)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->purchase_calculator_horizon: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
purchaseCalculatorHorizonRequest = ProtonApi::PurchaseCalculatorHorizonRequest.new
calculatorDepositSchedule = ProtonApi::CalculatorDepositSchedule1.new
begin
  purchaseCalculatorHorizonRequest.purchase_amount = 50000
  purchaseCalculatorHorizonRequest.portfolio_return = 0.06
  purchaseCalculatorHorizonRequest.current_savings = 1000
  calculatorDepositSchedule.deposit_amount = 1000
  calculatorDepositSchedule.deposit_frequency_interval = 'year'
  calculatorDepositSchedule.adjust_deposit_for_inflation = true
  purchaseCalculatorHorizonRequest.deposit_schedule = calculatorDepositSchedule
  purchaseCalculatorHorizonRequest.inflation_rate = 0.02
  purchaseCalculatorHorizonRequest.investment_tax = 0.25
  purchaseCalculatorHorizonResponse = api_instance.purchase_calculator_horizon(purchaseCalculatorHorizonRequest)
  p purchaseCalculatorHorizonResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling purchase_calculator_horizon #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$purchaseCalculatorHorizonRequest = new com\hydrogen\proton\Model\PurchaseCalculatorHorizonRequest();
try {

    $purchaseCalculatorHorizonRequest->setPurchaseAmount(50000);
    $purchaseCalculatorHorizonRequest->setPortfolioReturn(0.06);
    $purchaseCalculatorHorizonRequest->setCurrentSavings(1000);
    $calculatorDepositSchedule = new \com\hydrogen\proton\Model\CalculatorDepositSchedule1();
    $calculatorDepositSchedule->setDepositAmount(10000);
    $calculatorDepositSchedule->setDepositFrequencyInterval('year');
    $calculatorDepositSchedule->setAdjustDepositForInflation(true);
    $purchaseCalculatorHorizonRequest->setDepositSchedule($calculatorDepositSchedule);
    $purchaseCalculatorHorizonRequest->setInflationRate(0.02);
    $purchaseCalculatorHorizonRequest->setInvestmentTax(0.25);
    $result = $apiInstance->purchaseCalculatorHorizon($purchaseCalculatorHorizonRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->purchaseCalculatorHorizon: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
    var purchaseCalculatorHorizonRequest = new HydrogenProtonApi.PurchaseCalculatorHorizonRequest();
    purchaseCalculatorHorizonRequest.purchase_amount=50000;
    purchaseCalculatorHorizonRequest.portfolio_return=0.06;
    purchaseCalculatorHorizonRequest.current_savings=1000;
    purchaseCalculatorHorizonRequest.deposit_schedule= {
        "deposit_amount": 1000,
        "deposit_frequency_interval": "year",
        "adjust_deposit_for_inflation": true
    },
        purchaseCalculatorHorizonRequest.inflation_rate=0.02;
    purchaseCalculatorHorizonRequest.investment_tax=0.25;
    api.purchaseCalculatorHorizon(purchaseCalculatorHorizonRequest, callback)

ARGUMENTS

Parameter Description
purchase_amount
float, required
The amount of the major purchase.
portfolio_return
float, required
The portfolio’s return, calculated on an annual basis.
current_savings
float
The current amount of savings earmarked for the goal. If excluded, defaults to 0.
deposit_schedule
map
The deposit schedule for the major purchase goal.
      deposit_amount
      float
The periodic additions to the major purchase goal. If excluded, defaults to 0.
      deposit_frequency_interval
      string
The period interval to be used in relation to the deposit_amount. The value may be one of the following: year, quarter, month, or week. If excluded, defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposits are increased over time with the rate of inflation. If excluded, defaults to true.
inflation_rate
float
The annual inflation rate of the purchase_amount. If excluded, defaults to 0.
investment_tax
float
The tax on the investments used to pay for the major purchase. If excluded, defaults to 0.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive current_savings. If current_savings is not provided, we will try to use account_ids to derive this value instead.

Example Response

{
    "purchase_horizon": 7,
    "purchase_horizon_frequency_interval": "year",
    "adjusted_goal_amount": 76579.04,
    "projected_savings_at_purchase_horizon": 88736.15,
    "total_earnings": 14393.31,
    "total_contributions": 74342.83,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "ending_balance": 0
        },
        "1": {
            "period_earnings": 0,
            "period_contribution": 10000,
            "cumulative_earnings": 0,
            "cumulative_contributions": 10000,
            "ending_balance": 10000
        },
        "2": {
            "period_earnings": 600,
            "period_contribution": 10200,
            "cumulative_earnings": 600,
            "cumulative_contributions": 20200,
            "ending_balance": 20800
        },
        "3": {
            "period_earnings": 1248,
            "period_contribution": 10404,
            "cumulative_earnings": 1848,
            "cumulative_contributions": 30604,
            "ending_balance": 32452
        },
        "4": {
            "period_earnings": 1947.12,
            "period_contribution": 10612.08,
            "cumulative_earnings": 3795.12,
            "cumulative_contributions": 41216.08,
            "ending_balance": 45011.2
        },
        "5": {
            "period_earnings": 2700.67,
            "period_contribution": 10824.32,
            "cumulative_earnings": 6495.79,
            "cumulative_contributions": 52040.4,
            "ending_balance": 58536.19
        },
        "6": {
            "period_earnings": 3512.17,
            "period_contribution": 11040.81,
            "cumulative_earnings": 10007.96,
            "cumulative_contributions": 63081.21,
            "ending_balance": 73089.17
        },
        "7": {
            "period_earnings": 4385.35,
            "period_contribution": 11261.62,
            "cumulative_earnings": 14393.31,
            "cumulative_contributions": 74342.83,
            "ending_balance": 88736.15
        }
    }
}

RESPONSE

Field Description
purchase_horizon The number of periods needed in order to meet the major purchase goal.
purchase_horizon_frequency_interval The unit of time associated with purchase_horizon. Will always be year.
adjusted_goal_amount The effective goal target amount, adjusted for taxes and inflation.
projected_savings_at_purchase_horizon The total amount of savings that are projected to be available at the major purchase date, expressed in today’s dollars.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made.
      period_contribution
      
The deposit made for this period.
      cumulative_earnings
      
The cumulative earnings made up to and including this period.
      cumulative_contributions
      
The cumulative deposits made up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Mortgage Calculator

Many users face the question of how much a mortgage may cost when deciding to buy a property. This tool simplifies the parameters to five components: the mortgage interest rate, mortgage term, home price, down payment, and the periodic (monthly) payment. Of those five parameters, this mortgage calculator provides three different endpoints to solve for the following parameters: a periodic (monthly) payment, down payment and total home price.

Down Payment

This calculator helps a user solve for the down payment they will need to pay, given the other factors in their home purchase.

HTTP REQUEST

POST /mortgage_calculator/down_payment

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "home_price": 100000,
        "periodic_payment": 8000,
        "interest_rate": 0.04,
        "mortgage_term": 6
    }' "https://api.hydrogenplatform.com/proton/v1/mortgage_calculator/down_payment"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
       MortgageCalculatorDownPaymentRequest mortgageCalculatorDownPaymentRequest =
               new MortgageCalculatorDownPaymentRequest();
       mortgageCalculatorDownPaymentRequest.setHomePrice(10000F);
       mortgageCalculatorDownPaymentRequest.setPeriodicPayment(800F);
       mortgageCalculatorDownPaymentRequest.setInterestRate(0.04F);
       mortgageCalculatorDownPaymentRequest.setMortgageTerm(6);
       Map<String, Object> mortgageCalculatorDownPaymentResponse =
               financialPlanningApi.mortgageCalculatorDownPayment(mortgageCalculatorDownPaymentRequest);
       System.out.println(mortgageCalculatorDownPaymentResponse);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
mortgage_calculator_down_payment_request = proton_api.MortgageCalculatorDownPaymentRequest(
    home_price=10000, periodic_payment=800, interest_rate=0.04, mortgage_term=6
)
try:
    # Financial Planning - Mortgage Calculator Down Payment
    api_response = api_instance.mortgage_calculator_down_payment(mortgage_calculator_down_payment_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->mortgage_calculator_down_payment: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
mortgageCalculatorDownPaymentRequest = ProtonApi::MortgageCalculatorDownPaymentRequest.new
begin
  mortgageCalculatorDownPaymentRequest.home_price = 100000
  mortgageCalculatorDownPaymentRequest.periodic_payment = 800
  mortgageCalculatorDownPaymentRequest.interest_rate = 0.04
  mortgageCalculatorDownPaymentRequest.mortgage_term = 6
  mortgageCalculatorResponse = api_instance.mortgage_calculator_down_payment(mortgageCalculatorDownPaymentRequest)
  p mortgageCalculatorResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling mortgage_Calculator_Down_Payment_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$mortgageCalculatorDownPaymentRequest = new com\hydrogen\proton\Model\MortgageCalculatorDownPaymentRequest();
try {

    $mortgageCalculatorDownPaymentRequest->setHomePrice(100000);
    $mortgageCalculatorDownPaymentRequest->setPeriodicPayment(8000);
    $mortgageCalculatorDownPaymentRequest->setInterestRate(0.04);
    $mortgageCalculatorDownPaymentRequest->setMortgageTerm(6);

    $result = $apiInstance->mortgageCalculatorDownPayment($mortgageCalculatorDownPaymentRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->mortgageCalculatorDownPayment: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
    var mortgageCalculatorDownPaymentRequest = new HydrogenProtonApi.MortgageCalculatorDownPaymentRequest();
    mortgageCalculatorDownPaymentRequest.home_price=10000;
    mortgageCalculatorDownPaymentRequest.periodic_payment=800;
    mortgageCalculatorDownPaymentRequest.interest_rate=0.04;
    mortgageCalculatorDownPaymentRequest.mortgage_term=6;
    api.mortgageCalculatorDownPayment(mortgageCalculatorDownPaymentRequest, callback);

ARGUMENTS

Parameter Description
home_price
float, required
The total cost of the home, including down payments but excluding transactional costs of purchasing the home (e.g. insurance, legal fees, closing costs, etc.)
periodic_payment
float, required
The periodic monthly payment for the mortgage.
interest_rate
float
The annualized interest rate charged on the balance of the mortgage. If excluded, defaults to 0.0.
mortgage_term
integer
The length of time the mortgage will take place, as expressed in months. If excluded, defaults to 360.

Example Response

{
    "down_payment": 52545.22,
    "total_payment": 48000,
    "total_principal": 47454.78,
    "total_interest": 545.22,
    "total_home_cost": 100545.22,
    "schedule": {
        "0": {
            "Payment": 0,
            "Principal": 0,
            "Interest": 0,
            "Cumulative_Payment": 0,
            "Cumulative_Principal": 0,
            "Cumulative_Interest": 0,
            "Balance": 47454.78
        },
        "1": {
            "Payment": 8000,
            "Principal": 7844.65,
            "Interest": 155.35,
            "Cumulative_Payment": 8000,
            "Cumulative_Principal": 7844.65,
            "Cumulative_Interest": 155.35,
            "Balance": 39610.13
        },
        "2": {
            "Payment": 8000,
            "Principal": 7870.33,
            "Interest": 129.67,
            "Cumulative_Payment": 16000,
            "Cumulative_Principal": 15714.97,
            "Cumulative_Interest": 285.03,
            "Balance": 31739.81
        },
        "3": {
            "Payment": 8000,
            "Principal": 7896.09,
            "Interest": 103.91,
            "Cumulative_Payment": 24000,
            "Cumulative_Principal": 23611.06,
            "Cumulative_Interest": 388.94,
            "Balance": 23843.71
        },
        "4": {
            "Payment": 8000,
            "Principal": 7921.94,
            "Interest": 78.06,
            "Cumulative_Payment": 32000,
            "Cumulative_Principal": 31533.01,
            "Cumulative_Interest": 466.99,
            "Balance": 15921.77
        },
        "5": {
            "Payment": 8000,
            "Principal": 7947.88,
            "Interest": 52.12,
            "Cumulative_Payment": 40000,
            "Cumulative_Principal": 39480.88,
            "Cumulative_Interest": 519.12,
            "Balance": 7973.9
        },
        "6": {
            "Payment": 8000,
            "Principal": 7973.9,
            "Interest": 26.1,
            "Cumulative_Payment": 48000,
            "Cumulative_Principal": 47454.78,
            "Cumulative_Interest": 545.22,
            "Balance": 0
        }
    }
}

RESPONSE

Field Description
down_payment The payment due upfront when buying a home, given the other inputs provided by the user.
total_payment The total mortgage payments made over mortgage_term.
total_principal The total amount that went toward the mortgage principal.
total_interest The total amount that went toward the mortgage interest.
total_home_cost The total cost of the home, including down payment and all mortgage payments. This value is greater than home_price when interest_rate is greater than 0.
schedule Details for the mortgage payment, broken down by period.
      Payment
      
The total payment made for this period, consisting of interest and principal.
      Principal
      
The principal payment made for this period.
      Interest
      
The interest payment made for this period.
      Cumulative_Payment
      
The cumulative total payment made up to and including this period.
      Cumulative_Principal
      
The cumulative principal payment made up to and including this period.
      Cumulative_Interest
      
The cumulative interest payment made up to and including this period.
      Balance
      
The remaining mortgage balance at the end of the period.

Home Price

This calculator helps a user solve for the total home price they can afford, given the other factors related to their home purchase.

HTTP REQUEST

POST /mortgage_calculator/home_price

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "down_payment": 50000,
        "periodic_payment": 8000,
        "interest_rate": 0.04,
        "mortgage_term": 6
    }' "https://api.hydrogenplatform.com/proton/v1/mortgage_calculator/home_price"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
       MortgageCalculatorHomePriceRequest mortgageCalculatorHomePriceRequest =  new MortgageCalculatorHomePriceRequest();
       mortgageCalculatorHomePriceRequest.setDownPayment(50000F);
       mortgageCalculatorHomePriceRequest.setPeriodicPayment(8000F);
       mortgageCalculatorHomePriceRequest.setInterestRate(0.04F);
       mortgageCalculatorHomePriceRequest.setMortgageTerm(6);
       Map<String, Object> mortgageCalculatorHomePriceResponse =
               financialPlanningApi.mortgageCalculatorHomePrice(
                       mortgageCalculatorHomePriceRequest
               );
       System.out.println(mortgageCalculatorHomePriceResponse);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
mortgage_calculator_home_price_request = proton_api.MortgageCalculatorHomePriceRequest(
    down_payment=50000, periodic_payment=8000, interest_rate=0.04, mortgage_term=6
)
try:
    # Financial Planning - Mortgage Calculator Home Price
    api_response = api_instance.mortgage_calculator_home_price(mortgage_calculator_home_price_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->mortgage_calculator_home_price: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
mortgageCalculatorHomePriceRequest = ProtonApi::MortgageCalculatorHomePriceRequest.new
begin
  mortgageCalculatorHomePriceRequest.interest_rate = 0.04
  mortgageCalculatorHomePriceRequest.down_payment = 50000
  mortgageCalculatorHomePriceRequest.periodic_payment = 8000
  mortgageCalculatorHomePriceRequest.mortgage_term = 6
  mortgageCalculatorHomePriceResponse = api_instance.mortgage_calculator_home_price(mortgageCalculatorHomePriceRequest)
  p mortgageCalculatorHomePriceResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling monte_Carlo_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$mortgageCalculatorHomePriceRequest = new com\hydrogen\proton\Model\MortgageCalculatorHomePriceRequest();
try {

    $mortgageCalculatorHomePriceRequest->setDownPayment(50000);
    $mortgageCalculatorHomePriceRequest->setPeriodicPayment(8000);
    $mortgageCalculatorHomePriceRequest->setInterestRate(0.04);
    $mortgageCalculatorHomePriceRequest->setMortgageTerm(6);

    $result = $apiInstance->mortgageCalculatorHomePrice($mortgageCalculatorHomePriceRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->mortgageCalculatorHomePrice: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
    var mortgageCalculatorHomePriceRequest = new HydrogenProtonApi.MortgageCalculatorHomePriceRequest();
    mortgageCalculatorHomePriceRequest.down_payment=50000;
    mortgageCalculatorHomePriceRequest.periodic_payment=8000;
    mortgageCalculatorHomePriceRequest.interest_rate=0.04;
    mortgageCalculatorHomePriceRequest.mortgage_term=6;
    api.mortgageCalculatorHomePrice(mortgageCalculatorHomePriceRequest, callback);

ARGUMENTS

Parameter Description
down_payment
float, required
The payment due upfront when buying a home.
periodic_payment
float, required
The periodic monthly payment for the mortgage.
interest_rate
float
The annualized interest rate charged on the balance of the mortgage. If excluded, defaults to 0.0.
mortgage_term
integer
The length of time the mortgage will take place, as expressed in months. If excluded, defaults to 360.

Example Response

{
    "home_price": 97454.78,
    "total_payment": 48000,
    "total_principal": 47454.78,
    "total_interest": 545.22,
    "total_home_cost": 98000,
    "schedule": {
        "0": {
            "Payment": 0,
            "Principal": 0,
            "Interest": 0,
            "Cumulative_Payment": 0,
            "Cumulative_Principal": 0,
            "Cumulative_Interest": 0,
            "Balance": 47454.78
        },
        "1": {
            "Payment": 8000,
            "Principal": 7844.65,
            "Interest": 155.35,
            "Cumulative_Payment": 8000,
            "Cumulative_Principal": 7844.65,
            "Cumulative_Interest": 155.35,
            "Balance": 39610.13
        },
        "2": {
            "Payment": 8000,
            "Principal": 7870.33,
            "Interest": 129.67,
            "Cumulative_Payment": 16000,
            "Cumulative_Principal": 15714.97,
            "Cumulative_Interest": 285.03,
            "Balance": 31739.81
        },
        "3": {
            "Payment": 8000,
            "Principal": 7896.09,
            "Interest": 103.91,
            "Cumulative_Payment": 24000,
            "Cumulative_Principal": 23611.06,
            "Cumulative_Interest": 388.94,
            "Balance": 23843.71
        },
        "4": {
            "Payment": 8000,
            "Principal": 7921.94,
            "Interest": 78.06,
            "Cumulative_Payment": 32000,
            "Cumulative_Principal": 31533.01,
            "Cumulative_Interest": 466.99,
            "Balance": 15921.77
        },
        "5": {
            "Payment": 8000,
            "Principal": 7947.88,
            "Interest": 52.12,
            "Cumulative_Payment": 40000,
            "Cumulative_Principal": 39480.88,
            "Cumulative_Interest": 519.12,
            "Balance": 7973.9
        },
        "6": {
            "Payment": 8000,
            "Principal": 7973.9,
            "Interest": 26.1,
            "Cumulative_Payment": 48000,
            "Cumulative_Principal": 47454.78,
            "Cumulative_Interest": 545.22,
            "Balance": 0
        }
    }
}

RESPONSE

Field Description
home_price The total cost of the home that can be afforded, given the other inputs provided by the user.
total_payment The total mortgage payments made over mortgage_term.
total_principal The total amount that went toward the mortgage principal.
total_interest The total amount that went toward the mortgage interest.
total_home_cost The total cost of the home, including down payment and all mortgage payments. This value is greater than home_price when interest_rate is greater than 0.
schedule Details for the mortgage payment, broken down by period.
      Payment
      
The total payment made for this period, consisting of interest and principal.
      Principal
      
The principal payment made for this period.
      Interest
      
The interest payment made for this period.
      Cumulative_Payment
      
The cumulative total payment made up to and including this period.
      Cumulative_Principal
      
The cumulative principal payment made up to and including this period.
      Cumulative_Interest
      
The cumulative interest payment made up to and including this period.
      Balance
      
The remaining mortgage balance at the end of the period.

Periodic Payment

This calculator helps a user solve for the monthly mortgage payment, given the other factors in their home purchase.

HTTP REQUEST

POST /mortgage_calculator/periodic_payment

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "home_price": 100000,
        "down_payment": 50000,
        "interest_rate": 0.04,
        "mortgage_term": 6
    }' "https://api.hydrogenplatform.com/proton/v1/mortgage_calculator/periodic_payment"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
       MortgageCalculatorPeriodicPaymentRequest mortgageCalculatorPeriodicPaymentRequest =  new MortgageCalculatorPeriodicPaymentRequest();
       mortgageCalculatorPeriodicPaymentRequest.setHomePrice(10000F);
       mortgageCalculatorPeriodicPaymentRequest.setDownPayment(5000F);
       mortgageCalculatorPeriodicPaymentRequest.setInterestRate(0.04F);
       mortgageCalculatorPeriodicPaymentRequest.setMortgageTerm(6);
       Map<String, Object> mortgageCalculatorPeriodicPaymentResponse =
               financialPlanningApi.mortgageCalculatorPeriodicPayment(mortgageCalculatorPeriodicPaymentRequest);
       System.out.println(mortgageCalculatorPeriodicPaymentResponse);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
mortgage_calculator_periodic_payment_request = proton_api.MortgageCalculatorPeriodicPaymentRequest(
    home_price=10000, down_payment=5000, interest_rate=0.04, mortgage_term=6
)
try:
    # Financial Planning - Mortgage Calculator Periodic Payment
    api_response = api_instance.mortgage_calculator_periodic_payment(mortgage_calculator_periodic_payment_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->mortgage_calculator_periodic_payment: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
mortgageCalculatorPeriodicPaymentRequest = ProtonApi::MortgageCalculatorPeriodicPaymentRequest.new
begin
  mortgageCalculatorPeriodicPaymentRequest.mortgage_term = 6
  mortgageCalculatorPeriodicPaymentRequest.interest_rate = 0.04
  mortgageCalculatorPeriodicPaymentRequest.down_payment = 50000
  mortgageCalculatorPeriodicPaymentRequest.home_price = 100000
  mortgageCalculatorPeriodicPaymentResponse = api_instance.mortgage_calculator_periodic_payment(mortgageCalculatorPeriodicPaymentRequest)
  p mortgageCalculatorPeriodicPaymentResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling mortgage_Calculator_Period_Payment_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$mortgageCalculatorPeriodicPaymentRequest = new com\hydrogen\proton\Model\MortgageCalculatorPeriodicPaymentRequest();
try {

    $mortgageCalculatorPeriodicPaymentRequest->setMortgageTerm(6);
    $mortgageCalculatorPeriodicPaymentRequest->setDownPayment(5000);
    $mortgageCalculatorPeriodicPaymentRequest->setInterestRate(0.04);
    $mortgageCalculatorPeriodicPaymentRequest->setHomePrice(10000);


    $result = $apiInstance->mortgageCalculatorPeriodicPayment($mortgageCalculatorPeriodicPaymentRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->mortgageCalculatorPeriodicPayment: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
var mortgagecalculatorrequest = new HydrogenProtonApi.MortgageCalculatorPeriodicPaymentRequest();

    mortgagecalculatorrequest.home_price = 10000;
    mortgagecalculatorrequest.down_payment = 1000;
    mortgagecalculatorrequest.interest_rate = 0.05;
    mortgagecalculatorrequest.mortgage_term = 6;

apiInstance.mortgageCalculatorPeriodicPayment(mortgagecalculatorrequest, callback);

ARGUMENTS

Parameter Description
home_price
float, required
The total cost of the home, including down payments but excluding transactional costs of purchasing the home (e.g. insurance, legal fees, closing costs, etc.)
down_payment
float, required
The payment due upfront when buying a home.
interest_rate
float
The annualized interest rate charged on the balance of the mortgage. If excluded, defaults to 0.0.
mortgage_term
integer
The length of time the mortgage will take place, as expressed in months. If excluded, defaults to 360.

Example Response

{
    "periodic_payment": 8429.08,
    "total_payment": 50574.46,
    "total_principal": 50000,
    "total_interest": 574.46,
    "total_home_cost": 100574.46,
    "schedule": {
        "0": {
            "Payment": 0,
            "Principal": 0,
            "Interest": 0,
            "Cumulative_Payment": 0,
            "Cumulative_Principal": 0,
            "Cumulative_Interest": 0,
            "Balance": 50000
        },
        "1": {
            "Payment": 8429.08,
            "Principal": 8265.39,
            "Interest": 163.69,
            "Cumulative_Payment": 8429.08,
            "Cumulative_Principal": 8265.39,
            "Cumulative_Interest": 163.69,
            "Balance": 41734.61
        },
        "2": {
            "Payment": 8429.08,
            "Principal": 8292.45,
            "Interest": 136.63,
            "Cumulative_Payment": 16858.15,
            "Cumulative_Principal": 16557.84,
            "Cumulative_Interest": 300.32,
            "Balance": 33442.16
        },
        "3": {
            "Payment": 8429.08,
            "Principal": 8319.6,
            "Interest": 109.48,
            "Cumulative_Payment": 25287.23,
            "Cumulative_Principal": 24877.44,
            "Cumulative_Interest": 409.8,
            "Balance": 25122.56
        },
        "4": {
            "Payment": 8429.08,
            "Principal": 8346.83,
            "Interest": 82.24,
            "Cumulative_Payment": 33716.31,
            "Cumulative_Principal": 33224.27,
            "Cumulative_Interest": 492.04,
            "Balance": 16775.73
        },
        "5": {
            "Payment": 8429.08,
            "Principal": 8374.16,
            "Interest": 54.92,
            "Cumulative_Payment": 42145.39,
            "Cumulative_Principal": 41598.43,
            "Cumulative_Interest": 546.96,
            "Balance": 8401.57
        },
        "6": {
            "Payment": 8429.08,
            "Principal": 8401.57,
            "Interest": 27.5,
            "Cumulative_Payment": 50574.46,
            "Cumulative_Principal": 50000,
            "Cumulative_Interest": 574.46,
            "Balance": 0
        }
    }
}

RESPONSE

Field Description
periodic_payment The periodic monthly payment for the mortgage, given the other inputs provided by the user.
total_payment The total mortgage payments made over mortgage_term.
total_principal The total amount that went toward the mortgage principal.
total_interest The total amount that went toward the mortgage interest.
total_home_cost The total cost of the home, including down payment and all mortgage payments. This value is greater than home_price when interest_rate is greater than 0.
schedule Details for the mortgage payment, broken down by period.
      Payment
      
The total payment made for this period, consisting of interest and principal.
      Principal
      
The principal payment made for this period.
      Interest
      
The interest payment made for this period.
      Cumulative_Payment
      
The cumulative total payment made up to and including this period.
      Cumulative_Principal
      
The cumulative principal payment made up to and including this period.
      Cumulative_Interest
      
The cumulative interest payment made up to and including this period.
      Balance
      
The remaining mortgage balance at the end of the period.

Retirement Calculator

When planning for retirement, investors need to determine how much is needed and how to bridge any gaps in their financial plan. After collecting information about the user’s financial situation and desired retirement lifestyle, this tool solves for three different parameters: deposit amount, retirement lifestyle, and retirement expenses.

Deposit Amount

A calculator to help plan for the deposit amount needed to retire comfortably.

HTTP REQUEST

POST /retirement_calculator/deposit_amount

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "current_age": 70,
        "death_age": 78,
        "retirement_expenses": 40000,
        "portfolio_return": 0.06,
        "retirement_age":75,
        "percent_of_expenses_covered": 0.25,
        "retirement_savings": 5000,
        "retirement_income": 5000,
        "deposit_schedule": {
           "deposit_frequency_interval": "year",
           "adjust_deposit_for_inflation": true
        },
        "inflation_rate": 0.02,
        "retirement_tax": 0.25
    }' "https://api.hydrogenplatform.com/proton/v1/retirement_calculator/deposit_amount"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
       RetirementCalculatorDepositAmountRequest retirementCalculatorDepositAmountRequest =
               new RetirementCalculatorDepositAmountRequest();
       retirementCalculatorDepositAmountRequest.setCurrentAge(70);
       retirementCalculatorDepositAmountRequest.setDeathAge(78);
       retirementCalculatorDepositAmountRequest.setRetirementExpenses(5000F);
       retirementCalculatorDepositAmountRequest.setPortfolioReturn(0.06F);
       retirementCalculatorDepositAmountRequest.setRetirementAge(75);
       retirementCalculatorDepositAmountRequest.setPercentOfExpensesCovered(1F);
       retirementCalculatorDepositAmountRequest.setRetirementSavings(5000F);
       retirementCalculatorDepositAmountRequest.setRetirementIncome(5000F);
       retirementCalculatorDepositAmountRequest.setInflationRate(0.02F);
       retirementCalculatorDepositAmountRequest.setRetirementTax(0.25F);
       CalculatorDepositSchedule calculatorDepositSchedule2 = new CalculatorDepositSchedule();
       calculatorDepositSchedule2.setDepositFrequencyInterval(CalculatorDepositSchedule.DepositFrequencyIntervalEnum.YEAR);
       calculatorDepositSchedule2.setAdjustDepositForInflation(Boolean.TRUE);
       retirementCalculatorDepositAmountRequest.setDepositSchedule(calculatorDepositSchedule2);
       Map<String, Object> retirementCalculatorDepositAmountResponse =
               financialPlanningApi.retirementCalculatorDepositAmount(retirementCalculatorDepositAmountRequest);
       System.out.println(retirementCalculatorDepositAmountResponse);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
retirement_calculator_deposit_amount = proton_api.RetirementCalculatorDepositAmountRequest(
    current_age=70, death_age=78, retirement_expenses=5000, portfolio_return=0.06, retirement_age=75, percent_of_expenses_covered=1,
    retirement_savings=5000, retirement_income=5000, inflation_rate=0.02, retirement_tax=0.25,
    deposit_schedule=proton_api.CalculatorDepositSchedule(
        deposit_frequency_interval='year', adjust_deposit_for_inflation=True
    )
)
try:
    # Financial Planning - Retirement Calculator Deposit Amount
    api_response = api_instance.retirement_calculator_deposit_amount(retirement_calculator_deposit_amount)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->retirement_calculator_deposit_amount: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
retirementCalculatorDepositAmountRequest = ProtonApi::RetirementCalculatorDepositAmountRequest.new
calculatorDepositSchedule = ProtonApi::CalculatorDepositSchedule1.new
begin
  retirementCalculatorDepositAmountRequest.current_age = 70
  retirementCalculatorDepositAmountRequest.death_age = 78
  retirementCalculatorDepositAmountRequest.portfolio_return = 0.06
  retirementCalculatorDepositAmountRequest.percent_of_expenses_covered = 1
  retirementCalculatorDepositAmountRequest.retirement_expenses = 5000
  retirementCalculatorDepositAmountRequest.retirement_age = 75
  retirementCalculatorDepositAmountRequest.retirement_savings = 50000
  retirementCalculatorDepositAmountRequest.retirement_income = 5000
  calculatorDepositSchedule.deposit_frequency_interval = 'year'
  calculatorDepositSchedule.adjust_deposit_for_inflation =true
  retirementCalculatorDepositAmountRequest.deposit_schedule = calculatorDepositSchedule
  retirementCalculatorDepositAmountRequest.inflation_rate = 0.02
  retirementCalculatorDepositAmountRequest.retirement_tax =0.25
  retirementCalculatorDepositAmountResponse = api_instance.retirement_calculator_deposit_amount(retirementCalculatorDepositAmountRequest)
  p retirementCalculatorDepositAmountResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling retirement_calculator_deposit_amount_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$retirementCalculatorDepositAmountRequest = new com\hydrogen\proton\Model\RetirementCalculatorDepositAmountRequest();
try {

    $retirementCalculatorDepositAmountRequest->setCurrentAge(70);
    $retirementCalculatorDepositAmountRequest->setDeathAge(78);
    $retirementCalculatorDepositAmountRequest->setRetirementExpenses(5000);
    $retirementCalculatorDepositAmountRequest->setPortfolioReturn(0.06);
    $retirementCalculatorDepositAmountRequest->setPercentOfExpensesCovered(1);
    $retirementCalculatorDepositAmountRequest->setRetirementAge(75);
    $retirementCalculatorDepositAmountRequest->setRetirementSavings(5000);
    $retirementCalculatorDepositAmountRequest->setRetirementIncome(5000);

    $retirementCalculatorDepositSchedule = new \com\hydrogen\proton\Model\CalculatorDepositSchedule();
    $retirementCalculatorDepositSchedule->setDepositFrequencyInterval('year');
    $retirementCalculatorDepositSchedule->setAdjustDepositForInflation(true);
    $retirementCalculatorDepositAmountRequest->setDepositSchedule($retirementCalculatorDepositSchedule);

    $retirementCalculatorDepositAmountRequest->setInflationRate(0.02);
    $retirementCalculatorDepositAmountRequest->setRetirementTax(0.25);

    $result = $apiInstance->retirementCalculatorDepositAmount($retirementCalculatorDepositAmountRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->retirementCalculatorDepositAmount: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
    var retirementCalculatorDepositAmountRequest=new HydrogenProtonApi.RetirementCalculatorDepositAmountRequest();
    retirementCalculatorDepositAmountRequest.current_age=70;
    retirementCalculatorDepositAmountRequest.death_age=78;
    retirementCalculatorDepositAmountRequest.portfolio_return=0.06;
    retirementCalculatorDepositAmountRequest.percent_of_expenses_covered=1;
    retirementCalculatorDepositAmountRequest.retirement_expenses=5000;
    retirementCalculatorDepositAmountRequest.retirement_age=75;
    retirementCalculatorDepositAmountRequest.retirement_savings=50000;
    retirementCalculatorDepositAmountRequest.retirement_income=5000;
    retirementCalculatorDepositAmountRequest.deposit_schedule= {

        "deposit_frequency_interval": "year",
        "adjust_deposit_for_inflation": true
    },
        retirementCalculatorDepositAmountRequest.inflation_rate=0.02;
    retirementCalculatorDepositAmountRequest.investment_tax=0.25;
    api.retirementCalculatorDepositAmount(retirementCalculatorDepositAmountRequest, callback)

ARGUMENTS

Parameter Description
current_age
integer, required
The user’s current age. This will be used when determining the amount of years to accumulate funds.
death_age
integer, required
The user’s death age. This age will be used when determining the amount of years that retirement_expenses will be needed.
retirement_expenses
float, required
The desired annual living expenses or lifestyle in retirement.
portfolio_return
float, required
The portfolio’s annualized return.
retirement_age
integer
The age the user will retire. This is the age that the user will cease adding to their retirement assets and begin drawing down funds to meet retirement_expenses. If excluded, defaults to 65.
percent_of_expenses_covered
float
The percentage of current expenses needed in retirement. If excluded, defaults to 0.70.
retirement_savings
float
The current amount of retirement savings. If excluded, defaults to 0.
retirement_income
float
The amount of an income stream that will be available in retirement, expressed in today’s dollars. If excluded, defaults to 0.
deposit_schedule
map
The deposit schedule for the retirement goal.
      deposit_frequency_interval
      string
The frequency at which to make additions to retirement_savings in the periods before retirement. The value may be one of the following: year, quarter, month, or week. If excluded, defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposit_amount will be increased by the inflation_rate. If excluded, defaults to true.
inflation_rate
float
The annual inflation rate of retirement_expenses. If excluded, defaults to 0.
retirement_tax
float
The tax on assets in retirement. This tax rate will be applied to the assets that are needed for retirement_expenses. If excluded, defaults to 0.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive retirement_savings. If retirement_savings is not provided, we will try to use account_ids to derive this value instead.

Example Response

{
    "deposit_amount": 2351.62,
    "deposit_frequency_interval": "year",
    "projected_savings_at_retirement": 20456.61,
    "total_earnings": 5738.8,
    "total_contributions": 12237.92,
    "total_withdrawals": 17232.54,
    "total_taxes": 5744.18,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 5000
        },
        "1": {
            "period_earnings": 300,
            "period_contribution": 2351.62,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 2351.62,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 7651.62
        },
        "2": {
            "period_earnings": 459.1,
            "period_contribution": 2398.65,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 759.1,
            "cumulative_contributions": 4750.27,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 10509.37
        },
        "3": {
            "period_earnings": 630.56,
            "period_contribution": 2446.62,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 1389.66,
            "cumulative_contributions": 7196.89,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 13586.55
        },
        "4": {
            "period_earnings": 815.19,
            "period_contribution": 2495.56,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 2204.85,
            "cumulative_contributions": 9692.45,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 16897.3
        },
        "5": {
            "period_earnings": 1013.84,
            "period_contribution": 2545.47,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 3218.69,
            "cumulative_contributions": 12237.92,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 20456.61
        },
        "6": {
            "period_earnings": 1227.4,
            "period_contribution": 0,
            "period_withdrawal": -5630.81,
            "period_taxes": -1876.94,
            "cumulative_earnings": 4446.09,
            "cumulative_contributions": 12237.92,
            "cumulative_withdrawals": -5630.81,
            "cumulative_taxes": -1876.94,
            "ending_balance": 14176.26
        },
        "7": {
            "period_earnings": 850.58,
            "period_contribution": 0,
            "period_withdrawal": -5743.43,
            "period_taxes": -1914.48,
            "cumulative_earnings": 5296.66,
            "cumulative_contributions": 12237.92,
            "cumulative_withdrawals": -11374.24,
            "cumulative_taxes": -3791.41,
            "ending_balance": 7368.93
        },
        "8": {
            "period_earnings": 442.14,
            "period_contribution": 0,
            "period_withdrawal": -5858.3,
            "period_taxes": -1952.77,
            "cumulative_earnings": 5738.8,
            "cumulative_contributions": 12237.92,
            "cumulative_withdrawals": -17232.54,
            "cumulative_taxes": -5744.18,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
deposit_amount The amount to deposit in order to meet the retirement goal.
deposit_frequency_interval The frequency interval of the deposit.
projected_savings_at_retirement The total amount of savings projected to be available at retirement, expressed in today’s dollars.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_withdrawals The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      period_contribution
      
The deposit made for this period.
      period_withdrawal
      
The withdrawal made for this period.
      period_taxes
      
The taxes paid during this period.
      cumulative_earnings
      
The cumulative investment earnings made up to and including this period.
      cumulative_contributions
      
The cumulative deposits made up to and including this period.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_taxes
      
The cumulative taxes paid up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Percent of Costs Covered

A calculator to help determine the percentage of the retirement lifestyle that can be afforded.

HTTP REQUEST

POST /retirement_calculator/percent_covered

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "current_age": 50,
        "death_age": 57,
        "retirement_expenses": 40000,
        "portfolio_return": 0.06,
        "retirement_age": 55,
        "retirement_savings": 5000,
        "retirement_income": 5000,
        "deposit_schedule": {
           "deposit_amount": 10000,
           "deposit_frequency_interval": "year",
           "adjust_deposit_for_inflation": true
        },
        "inflation_rate": 0.02,
        "retirement_tax": 0.25
    }' "https://api.hydrogenplatform.com/proton/v1/retirement_calculator/percent_covered"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
       RetirementCalculatorPercentCoveredRequest retirementCalculatorPercentCoveredRequest =
               new RetirementCalculatorPercentCoveredRequest();
       retirementCalculatorPercentCoveredRequest.setCurrentAge(50);
       retirementCalculatorPercentCoveredRequest.setDeathAge(57);
       retirementCalculatorPercentCoveredRequest.setRetirementExpenses(4000F);
       retirementCalculatorPercentCoveredRequest.setPortfolioReturn(0.06F);
       retirementCalculatorPercentCoveredRequest.setRetirementAge(55);
       retirementCalculatorPercentCoveredRequest.setRetirementSavings(5000F);
       retirementCalculatorPercentCoveredRequest.setRetirementIncome(5000F);
       retirementCalculatorPercentCoveredRequest.setInflationRate(0.02F);
       retirementCalculatorPercentCoveredRequest.setRetirementTax(0.25F);
       retirementCalculatorPercentCoveredRequest.setDepositSchedule(retirementCalculatorDepositSchedule);
       Map<String, Object> retirementCalculatorPercentCoveredResponse =
               financialPlanningApi.retirementCalculatorPercentCovered(retirementCalculatorPercentCoveredRequest);
       System.out.println(retirementCalculatorPercentCoveredResponse);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
retirement_calculator_percent_covered = proton_api.RetirementCalculatorPercentCoveredRequest(
    current_age=50, death_age=57, retirement_expenses=4000, portfolio_return=0.06, retirement_age=55,
    retirement_savings=5000, retirement_income=5000, inflation_rate=0.02, retirement_tax=0.25, deposit_schedule=
    proton_api.CalculatorDepositSchedule1(
        deposit_amount=1000, adjust_deposit_for_inflation=True, deposit_frequency_interval='year'
    )
)
try:
    # Financial Planning - Retirement Calculator Percent Covered
    api_response = api_instance.retirement_calculator_percent_covered(retirement_calculator_percent_covered)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->retirement_calculator_percent_covered: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
retirementCalculatorPercentCoveredRequest = ProtonApi::RetirementCalculatorPercentCoveredRequest.new
calculatorDepositSchedule = ProtonApi::CalculatorDepositSchedule1.new
begin
  retirementCalculatorPercentCoveredRequest.current_age = 50
  retirementCalculatorPercentCoveredRequest.death_age = 57
  retirementCalculatorPercentCoveredRequest.retirement_expenses = 4000
  retirementCalculatorPercentCoveredRequest.portfolio_return = 0.06
  retirementCalculatorPercentCoveredRequest.retirement_age = 55
  retirementCalculatorPercentCoveredRequest.retirement_savings = 50000
  retirementCalculatorPercentCoveredRequest.retirement_income = 5000
  calculatorDepositSchedule.deposit_amount =1000
  calculatorDepositSchedule.deposit_frequency_interval ='year'
  calculatorDepositSchedule.adjust_deposit_for_inflation =true
  retirementCalculatorPercentCoveredRequest.deposit_schedule = calculatorDepositSchedule
  retirementCalculatorPercentCoveredRequest.inflation_rate = 0.02
  retirementCalculatorPercentCoveredRequest.retirement_tax = 0.25
  educationCalculatorPercentCoveredResponse = api_instance.retirement_calculator_percent_covered(retirementCalculatorPercentCoveredRequest)
  p educationCalculatorPercentCoveredResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling retirement_calculator_percent_covered_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$retirementCalculatorPercentCoveredRequest = new com\hydrogen\proton\Model\RetirementCalculatorPercentCoveredRequest();
try {

    $retirementCalculatorPercentCoveredRequest->setCurrentAge(50);
    $retirementCalculatorPercentCoveredRequest->setDeathAge(57);
    $retirementCalculatorPercentCoveredRequest->setRetirementExpenses(4000);
    $retirementCalculatorPercentCoveredRequest->setPortfolioReturn(0.06);
    $retirementCalculatorPercentCoveredRequest->setRetirementAge(55);
    $retirementCalculatorPercentCoveredRequest->setRetirementSavings(5000);
    $retirementCalculatorPercentCoveredRequest->setRetirementIncome(5000);
    $retirementCalculatorPercentCoveredRequest->setInflationRate(0.02);
    $retirementCalculatorPercentCoveredRequest->setRetirementTax(0.25);

    $result = $apiInstance->retirementCalculatorPercentCovered($retirementCalculatorPercentCoveredRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->retirementCalculatorPercentCovered: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
    var retirementCalculatorPercentCoveredRequest= new HydrogenProtonApi.RetirementCalculatorPercentCoveredRequest();
    retirementCalculatorPercentCoveredRequest.current_age=50;
    retirementCalculatorPercentCoveredRequest.death_age=57;
    retirementCalculatorPercentCoveredRequest.portfolio_return=0.06;
    retirementCalculatorPercentCoveredRequest.retirement_age=55;
    retirementCalculatorPercentCoveredRequest.retirement_expenses=4000;
    retirementCalculatorPercentCoveredRequest.retirement_savings=50000;
    retirementCalculatorPercentCoveredRequest.retirement_income=5000;
    retirementCalculatorPercentCoveredRequest.deposit_schedule= {
        "deposit_frequency_interval": "year",
        "adjust_deposit_for_inflation": true
    },
        retirementCalculatorPercentCoveredRequest.inflation_rate=0.02;
    retirementCalculatorPercentCoveredRequest.retirement_tax=0.25;
    api.retirementCalculatorPercentCovered(retirementCalculatorPercentCoveredRequest, callback)

ARGUMENTS

Parameter Description
current_age
integer, required
The user’s current age. This will be used when determining the amount of years to accumulate funds.
death_age
integer, required
The user’s death age. This age will be used when determining the amount of years that retirement_expenses will be needed.
retirement_expenses
float, required
The desired annual living expenses or lifestyle in retirement.
portfolio_return
float, required
The portfolio’s annualized return.
retirement_age
integer
The age the user will retire. This is the age that the user will cease adding to their retirement assets and begin drawing down funds to meet retirement_expenses. If excluded, defaults to 65.
retirement_savings
float
The current amount of retirement savings. If excluded, defaults to 0.
retirement_income
float
The amount of an income stream that will be available in retirement, expressed in today’s dollars. If excluded, defaults to 0.
deposit_schedule
map
The deposit schedule for the retirement goal.
      deposit_amount
      float
The periodic additions to retirement savings in the period before retirement. If excluded, defaults to 0.
      deposit_frequency_interval
      string
The frequency at which to make additions to retirement savings in the periods before retirement. The value may be one of the following: year, quarter, month, or week. If excluded, defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposit_amount will be increased by the inflation_rate. If excluded, defaults to true.
inflation_rate
float
The annual inflation rate of retirement_expenses. If excluded, defaults to 0.
retirement_tax
float
The tax on assets in retirement. This tax rate will be applied to the assets that are needed for retirement_expenses. If excluded, defaults to 0.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive retirement_savings. If retirement_savings is not provided, we will try to use account_ids to derive this value instead.

Example Response

{
    "achievable_expenses": 23465.95,
    "target_expenses": 35000,
    "percent_of_expenses_covered": 0.6705,
    "projected_savings_at_retirement": 65227.32,
    "total_earnings": 14134.9,
    "total_contributions": 52040.4,
    "total_withdrawals": 53381.48,
    "total_taxes": 17793.83,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 5000
        },
        "1": {
            "period_earnings": 300,
            "period_contribution": 10000,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 10000,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 15300
        },
        "2": {
            "period_earnings": 918,
            "period_contribution": 10200,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 1218,
            "cumulative_contributions": 20200,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 26418
        },
        "3": {
            "period_earnings": 1585.08,
            "period_contribution": 10404,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 2803.08,
            "cumulative_contributions": 30604,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 38407.08
        },
        "4": {
            "period_earnings": 2304.42,
            "period_contribution": 10612.08,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 5107.5,
            "cumulative_contributions": 41216.08,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 51323.58
        },
        "5": {
            "period_earnings": 3079.42,
            "period_contribution": 10824.32,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 8186.92,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 65227.32
        },
        "6": {
            "period_earnings": 3913.64,
            "period_contribution": 0,
            "period_withdrawal": -26426.47,
            "period_taxes": -8808.82,
            "cumulative_earnings": 12100.56,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": -26426.47,
            "cumulative_taxes": -8808.82,
            "ending_balance": 33905.66
        },
        "7": {
            "period_earnings": 2034.34,
            "period_contribution": 0,
            "period_withdrawal": -26955,
            "period_taxes": -8985,
            "cumulative_earnings": 14134.9,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": -53381.48,
            "cumulative_taxes": -17793.83,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
achievable_expenses The annual living expenses or lifestyle that can be covered in retirement, expressed in today’s dollars.
target_expenses The retirement_expenses input representing the target annual goal amount.
percent_of_expenses_covered The percentage of target_expenses that can be covered.
projected_savings_at_retirement The total amount of savings that are projected to be available at retirement, expressed in today’s dollars.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_withdrawals The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      period_contribution
      
The deposit made for this period.
      period_withdrawal
      
The withdrawal made for this period.
      period_taxes
      
The taxes paid during this period.
      cumulative_earnings
      
The cumulative investment earnings made up to and including this period.
      cumulative_contributions
      
The cumulative deposits made up to and including this period.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_taxes
      
The cumulative taxes paid up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Retirement Expenses

A calculator to help plan for the amount of expenses that will be incurred in retirement.

HTTP REQUEST

POST /retirement_calculator/expenses

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "current_age": 50,
        "death_age": 57,
        "portfolio_return": 0.06,
        "retirement_age": 55,
        "percent_of_expenses_covered": 0.25,
        "retirement_savings": 5000,
        "retirement_income": 5000,
        "deposit_schedule": {
           "deposit_amount": 10000,
           "deposit_frequency_interval": "year",
           "adjust_deposit_for_inflation": true
        },
        "inflation_rate": 0.02,
        "retirement_tax": 0.25
    }' "https://api.hydrogenplatform.com/proton/v1/retirement_calculator/expenses"
FinancialPlanningApi financialPlanningApi = new FinancialPlanningApi();
RetirementCalculatorExpensesRequest retirementCalculatorExpensesRequest = new RetirementCalculatorExpensesRequest();
retirementCalculatorExpensesRequest.setCurrentAge(50);
retirementCalculatorExpensesRequest.setDeathAge(57);
retirementCalculatorExpensesRequest.setPortfolioReturn(0.06F);
retirementCalculatorExpensesRequest.setRetirementAge(55);
retirementCalculatorExpensesRequest.setPercentOfExpensesCovered(1F);
retirementCalculatorExpensesRequest.setRetirementSavings(5000F);
retirementCalculatorExpensesRequest.setRetirementIncome(5000F);
retirementCalculatorExpensesRequest.setInflationRate(0.02F);
retirementCalculatorExpensesRequest.setRetirementTax(0.25F);
CalculatorDepositSchedule1 retirementCalculatorDepositSchedule =  new CalculatorDepositSchedule1();
retirementCalculatorDepositSchedule.setDepositAmount(1000F);
retirementCalculatorDepositSchedule.setAdjustDepositForInflation(Boolean.TRUE);
retirementCalculatorDepositSchedule.setDepositFrequencyInterval(CalculatorDepositSchedule1.DepositFrequencyIntervalEnum.YEAR);
retirementCalculatorExpensesRequest.setDepositSchedule(retirementCalculatorDepositSchedule);
Map<String, Object> retirementCalculatorExpenseResponse =
        financialPlanningApi.retirementCalculatorExpenses(retirementCalculatorExpensesRequest);
System.out.println(
        retirementCalculatorExpenseResponse
);
api_instance = proton_api.FinancialPlanningApi(proton_api.ApiClient(configuration))
retirement_calculator_expenses_request = proton_api.RetirementCalculatorExpensesRequest(
    current_age=50, death_age=57, portfolio_return=0.06, retirement_age=55, percent_of_expenses_covered=1, retirement_savings=5000,
    retirement_income=5000, inflation_rate=0.02, retirement_tax=0.25, deposit_schedule= proton_api.CalculatorDepositSchedule1(
        deposit_amount=1000, adjust_deposit_for_inflation=True, deposit_frequency_interval='year'
    )
)
try:
    # Financial Planning - Retirement Calculator Expenses
    api_response = api_instance.retirement_calculator_expenses(retirement_calculator_expenses_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FinancialPlanningApi->retirement_calculator_expenses: %s\n" % e)
api_instance = ProtonApi::FinancialPlanningApi.new
retirementCalculatorExpensesRequest = ProtonApi::RetirementCalculatorExpensesRequest.new
calculatorDepositSchedule = ProtonApi::CalculatorDepositSchedule1.new
begin
  retirementCalculatorExpensesRequest.current_age = 50
  retirementCalculatorExpensesRequest.death_age = 57
  retirementCalculatorExpensesRequest.portfolio_return = 0.06
  retirementCalculatorExpensesRequest.retirement_age = 55
  retirementCalculatorExpensesRequest.percent_of_expenses_covered = 1
  retirementCalculatorExpensesRequest.retirement_savings = 50000
  retirementCalculatorExpensesRequest.retirement_income = 5000
  calculatorDepositSchedule.deposit_amount =1000
  calculatorDepositSchedule.deposit_frequency_interval ='year'
  calculatorDepositSchedule.adjust_deposit_for_inflation =true
  retirementCalculatorExpensesRequest.deposit_schedule = calculatorDepositSchedule
  retirementCalculatorExpensesRequest.inflation_rate = 0.02
  retirementCalculatorExpensesRequest.retirement_tax = 0.25
  retirementCalculatorExpensesResponse = api_instance.retirement_calculator_expenses(retirementCalculatorExpensesRequest)
  p retirementCalculatorExpensesResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling retirement_calculator_expenses_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\FinancialPlanningApi(
    new GuzzleHttp\Client(),
    $config
);
$retirementCalculatorExpensesRequest = new com\hydrogen\proton\Model\RetirementCalculatorExpensesRequest();
try {

    $retirementCalculatorExpensesRequest->setCurrentAge(50);
    $retirementCalculatorExpensesRequest->setDeathAge(57);
    $retirementCalculatorExpensesRequest->setPortfolioReturn(0.06);
    $retirementCalculatorExpensesRequest->setPercentOfExpensesCovered(1);
    $retirementCalculatorExpensesRequest->setRetirementAge(55);
    $retirementCalculatorExpensesRequest->setRetirementSavings(50000);
    $retirementCalculatorExpensesRequest->setRetirementIncome(5000);

    $retirementDepositExpenseSchedule = new \com\hydrogen\proton\Model\CalculatorDepositSchedule1();
    $retirementDepositExpenseSchedule->setDepositAmount(1000);
    $retirementDepositExpenseSchedule->setDepositFrequencyInterval('year');
    $retirementDepositExpenseSchedule->setAdjustDepositForInflation(true);
    $retirementCalculatorExpensesRequest->setDepositSchedule($retirementDepositExpenseSchedule);

    $retirementCalculatorExpensesRequest->setInflationRate(0.02);
    $retirementCalculatorExpensesRequest->setRetirementTax(0.25);

    $result = $apiInstance->retirementCalculatorExpenses($retirementCalculatorExpensesRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FinancialPlanningAPI->retirementCalculatorExpenses: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.FinancialPlanningApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.FinancialPlanningApi();
    var retirementCalculatorExpensesRequest = new HydrogenProtonApi. RetirementCalculatorExpensesRequest();
    retirementCalculatorExpensesRequest.current_age=50;
    retirementCalculatorExpensesRequest.death_age=57;
    retirementCalculatorExpensesRequest.portfolio_return=0.06;
    retirementCalculatorExpensesRequest.retirement_age=55;
    retirementCalculatorExpensesRequest.percent_of_expenses_covered=1;
    retirementCalculatorExpensesRequest.retirement_savings=50000;
    retirementCalculatorExpensesRequest.retirement_income=5000;
    retirementCalculatorExpensesRequest.deposit_schedule= {
        "deposit_frequency_interval": "year",
        "adjust_deposit_for_inflation": true,
        deposit_amount:1000
    },
        retirementCalculatorExpensesRequest.inflation_rate=0.02;
    retirementCalculatorExpensesRequest.retirement_tax=0.25;
    api.retirementCalculatorExpenses(retirementCalculatorExpensesRequest, callback)

ARGUMENTS

Parameter Description
current_age
integer, required
The user’s current age. This will be used when determining the amount of years to accumulate funds.
death_age
integer, required
The user’s death age. This age will be used when determining the amount of years that retirement_expenses will be needed.
portfolio_return
float, required
The portfolio’s annualized return.
retirement_age
integer
The age the user will retire. This is the age that the user will cease adding to their retirement assets and begin drawing down funds to meet retirement_expenses. If excluded, defaults to 65.
percent_of_expenses_covered
float
The percentage of current expenses needed in retirement. If excluded, defaults to 0.70.
retirement_savings
float
The current amount of retirement savings. If excluded, defaults to 0.
retirement_income
float
The amount of an income stream that will be available in retirement, expressed in today’s dollars. If excluded, defaults to 0.
deposit_schedule
map
The deposit schedule for the retirement goal.
      deposit_amount
      float
The periodic additions to retirement savings in the period before retirement. If excluded, defaults to 0.
      deposit_frequency_interval
      string
The frequency at which to make additions to retirement savings in the periods before retirement. The value may be one of the following: year, quarter, month, or week. If excluded, defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposit_amount will be increased by the inflation_rate. If excluded, defaults to true.
inflation_rate
float
The annual inflation rate of retirement_expenses. If excluded, defaults to 0.
retirement_tax
float
The tax on assets in retirement. This tax rate will be applied to the assets that are needed for retirement_expenses. If excluded, defaults to 0.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive retirement_savings. If retirement_savings is not provided, we will try to use account_ids to derive this value instead.

Example Response

{
    "projected_retirement_expenses": 111336.69,
    "projected_retirement_expenses_adjusted": 98863.8,
    "projected_savings_at_retirement": 65227.32,
    "total_earnings": 14134.9,
    "total_contributions": 52040.4,
    "total_withdrawals": 53381.48,
    "total_taxes": 17793.83,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 5000
        },
        "1": {
            "period_earnings": 300,
            "period_contribution": 10000,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 10000,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 15300
        },
        "2": {
            "period_earnings": 918,
            "period_contribution": 10200,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 1218,
            "cumulative_contributions": 20200,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 26418
        },
        "3": {
            "period_earnings": 1585.08,
            "period_contribution": 10404,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 2803.08,
            "cumulative_contributions": 30604,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 38407.08
        },
        "4": {
            "period_earnings": 2304.42,
            "period_contribution": 10612.08,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 5107.5,
            "cumulative_contributions": 41216.08,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 51323.58
        },
        "5": {
            "period_earnings": 3079.42,
            "period_contribution": 10824.32,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 8186.92,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 65227.32
        },
        "6": {
            "period_earnings": 3913.64,
            "period_contribution": 0,
            "period_withdrawal": -26426.47,
            "period_taxes": -8808.82,
            "cumulative_earnings": 12100.56,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": -26426.47,
            "cumulative_taxes": -8808.82,
            "ending_balance": 33905.66
        },
        "7": {
            "period_earnings": 2034.34,
            "period_contribution": 0,
            "period_withdrawal": -26955,
            "period_taxes": -8985,
            "cumulative_earnings": 14134.9,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": -53381.48,
            "cumulative_taxes": -17793.83,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
projected_retirement_expenses The after-tax annual living expenses or lifestyle available in retirement.
projected_retirement_expenses_adjusted The after-tax annual living expenses or lifestyle available in retirement, expressed in today’s dollars.
projected_savings_at_retirement The total amount of savings that are projected to be available at retirement, expressed in today’s dollars.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_withdrawals The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      period_contribution
      
The deposit made for this period.
      period_withdrawal
      
The withdrawal made for this period.
      period_taxes
      
The taxes paid during this period.
      cumulative_earnings
      
The cumulative investment earnings made up to and including this period.
      cumulative_contributions
      
The cumulative deposits made up to and including this period.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_taxes
      
The cumulative taxes paid up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

NUCLEUS DATA DEPENDENCIES

Savings Calculator

While more detail is usually welcomed by financial professionals, some firms opt to provide simple calculators for simple savings or investing products. This endpoint provides a calculator that can show a simple growth of investment over time. After providing return, deposit, and balance information, the calculator returns an ending balance and simulation details. Earnings are calculated at the beginning of each period, before deposits for that period are considered. Tax rates, if provided, are applied in the return calculation. Returns are calculated at the same frequency stipulated in horizon_frequency_interval.

HTTP REQUEST

POST /savings_calculator

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "initial_balance": 10000,
        "horizon": 5,
        "return_schedule": [0.02, 0.025, 0.025, 0.025, 0.03],
        "horizon_frequency_interval": "year",
        "deposit_schedule":
        [
          {
            "deposit_amount": 100,
            "deposit_frequency_interval": "month",
            "deposit_duration": 120,
            "adjust_deposit_for_inflation": true
          },
          {
            "deposit_amount": 2000,
            "deposit_frequency_interval": "year",
            "deposit_duration": 10,
            "adjust_deposit_for_inflation": true
          }
        ],
        "tax_rate": 0.33,
        "inflation_rate": 0.02
      }' "https://api.hydrogenplatform.com/proton/v1/savings_calculator"
SimulationsApi simulationsApi = new SimulationsApi();
        SavingsCalculatorRequest savingsCalculatorRequest = new SavingsCalculatorRequest();
        savingsCalculatorRequest.setInitialBalance(BigDecimal.valueOf(10000));
        savingsCalculatorRequest.setHorizon(5);
        savingsCalculatorRequest.setReturnSchedule(Arrays.asList(
                0.02F,
                0.025F,
                0.025f,
                0.025F,
                0.03F
        ));
        savingsCalculatorRequest.setHorizonFrequencyInterval(SavingsCalculatorRequest.HorizonFrequencyIntervalEnum.YEAR);
        savingsCalculatorRequest.setTaxRate(0.33F);
        savingsCalculatorRequest.setInflationRate(0.02F);
        savingsCalculatorRequest.setCreateLog(FALSE);
        SavingsDepositSchedule savingsDepositSchedule = new SavingsDepositSchedule();
        savingsDepositSchedule.depositAmount(BigDecimal.valueOf(100));
        savingsDepositSchedule.setDepositFrequencyInterval(SavingsDepositSchedule.DepositFrequencyIntervalEnum.MONTH);
        savingsDepositSchedule.setDepositDuration(120);
        savingsDepositSchedule.setAdjustDepositForInflation(TRUE);
        SavingsDepositSchedule savingsDepositSchedule1 = new SavingsDepositSchedule();
        savingsDepositSchedule1.depositAmount(BigDecimal.valueOf(2000));
        savingsDepositSchedule1.setDepositFrequencyInterval(SavingsDepositSchedule.DepositFrequencyIntervalEnum.YEAR);
        savingsDepositSchedule1.setDepositDuration(10);
        savingsDepositSchedule1.setAdjustDepositForInflation(TRUE);
        savingsCalculatorRequest.setDepositSchedule(Arrays.asList(savingsDepositSchedule, savingsDepositSchedule1));
        try {
            Map<String, Object> savingsCalculatorResponse = simulationsApi.savingsCalculator(savingsCalculatorRequest);
            System.out.println(savingsCalculatorResponse);
        } catch (ApiException e) {
            e.printStackTrace();
        }
api_instance = proton_api.SimulationsApi(proton_api.ApiClient(configuration))
saving_calculator_request = proton_api.SavingsCalculatorRequest(
    initial_balance=10000, horizon=5, return_schedule=[0.02, 0.025, 0.025,0.025, 0.3],
    horizon_frequency_interval='year', tax_rate=0.33, inflation_rate=0.02, create_log=False,
    deposit_schedule=[
        proton_api.SavingsDepositSchedule(
            deposit_amount=100, deposit_frequency_interval='month', deposit_duration=120, adjust_deposit_for_inflation=True
        ),
        proton_api.SavingsDepositSchedule(
            deposit_amount=1000, deposit_frequency_interval='month', deposit_duration=10, adjust_deposit_for_inflation=True
        )
    ]
)
try:
    # SimulationsApi - Saving Calculator Request
    api_response = api_instance.savings_calculator(saving_calculator_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling SimulationsApi->savings_calculator: %s\n" % e)
api_instance = ProtonApi::SimulationsApi.new
savingsCalculatorRequest = ProtonApi::SavingsCalculatorRequest.new
begin
  savingsCalculatorRequest.initial_balance = 10000
  savingsCalculatorRequest.horizon = 5
  savingsCalculatorRequest.return_schedule = [0.02, 0.025, 0.025, 0.025, 0.03]
  savingsCalculatorRequest.horizon_frequency_interval = "year"
  savingsDepositSchedule = ProtonApi::SavingsDepositSchedule.new
  savingsDepositSchedule.deposit_amount = 100
  savingsDepositSchedule.deposit_frequency_interval = 'month'
  savingsDepositSchedule.deposit_duration = 120
  savingsDepositSchedule.adjust_deposit_for_inflation = true

  savingsDepositSchedule1 = ProtonApi::SavingsDepositSchedule.new
  savingsDepositSchedule1.deposit_amount = 1000
  savingsDepositSchedule1.deposit_frequency_interval = 'month'
  savingsDepositSchedule1.deposit_duration = 10
  savingsDepositSchedule1.adjust_deposit_for_inflation = true
  savingsCalculatorRequest.deposit_schedule =
      [
          savingsDepositSchedule, savingsDepositSchedule1
      ]
  savingsCalculatorRequest.tax_rate = 0.33
  savingsCalculatorRequest.inflation_rate = 0.02
  savingsCalculatorRequest.create_log = false
  savingsCalculatorResponse = api_instance.savings_calculator(savingsCalculatorRequest)
  p savingsCalculatorResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling savings_calculator_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\SimulationsApi(
    new GuzzleHttp\Client(),
    $config
);
$savingsCalculatorRequest = new com\hydrogen\proton\Model\SavingsCalculatorRequest();
try {

    $savingsCalculatorRequest->setInitialBalance(10000);
    $savingsCalculatorRequest->setHorizon(5);
    $savingsCalculatorRequest->setReturnSchedule(array(0.02, 0.025, 0.025, 0.025, 0.03));
    $savingsCalculatorRequest->setHorizonFrequencyInterval("year");

    $depositSchedule = new \com\hydrogen\proton\Model\SavingsDepositSchedule();
    $depositSchedule->setDepositAmount(100);
    $depositSchedule->setDepositFrequencyInterval("month");
    $depositSchedule->setDepositDuration(120);
    $depositSchedule->setAdjustDepositForInflation(true);
    $savingsCalculatorRequest->setDepositSchedule(array($depositSchedule));

    $savingsCalculatorRequest->setInflationRate(0.02);
    $savingsCalculatorRequest->setTaxRate(0.33);

    $result = $apiInstance->savingsCalculator($savingsCalculatorRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling SimulationsApi->savingsCalculator: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.SimulationsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.SimulationsApi();
    var savingsCalculatorRequest = new HydrogenProtonApi.SavingsCalculatorRequest();
    savingsCalculatorRequest.initial_balance=10000;
    savingsCalculatorRequest.horizon=5;
    savingsCalculatorRequest.return_schedule=[0.02, 0.025, 0.025, 0.025, 0.03];
    savingsCalculatorRequest.horizon_frequency_interval= "year";
    savingsCalculatorRequest.deposit_schedule=
        [
            {
                "deposit_amount": 100,
                "deposit_frequency_interval": "month",
                "deposit_duration": 120,
                "adjust_deposit_for_inflation": true
            },
            {
                "deposit_amount": 2000,
                "deposit_frequency_interval": "year",
                "deposit_duration": 10,
                "adjust_deposit_for_inflation": true
            }
        ];
    savingsCalculatorRequest.tax_rate= 0.33;
    savingsCalculatorRequest.inflation_rate= 0.02;
    savingsCalculatorRequest.createLog = false;
    api.savingsCalculator(savingsCalculatorRequest, callback)

ARGUMENTS

Parameter Description
horizon
integer, required
The number of time periods in the savings horizon, where each period represents horizon_frequency_interval.
return_schedule
array, required
The rate of return per period. Providing an array of length 1, such as [0.04], will apply the value to each period in horizon.
horizon_frequency_interval
string
The frequency interval for horizon. Must be one of year, quarter, month, week, or day. Defaults to year.
initial_balance
float
The initial balance of the investment. Defaults to 0.
deposit_schedule
array[map]
Details on the deposit plan. If excluded, no deposits are included in the calculation.
      deposit_amount
      float
The amount deposited in a given period and frequency. If excluded, defaults to 0.
      deposit_frequency_interval
      string
The period interval to be used in relation to deposit_duration. Must be one of year, quarter, month, week, or day. Defaults to year.
      deposit_duration
      string
The amount of intervals for the time period. If excluded, defaults to the number of intervals given in horizon.
      adjust_deposit_for_inflation
      boolean
If true, adjusts the deposit using the inflation_rate. If excluded, defaults to true.
tax_rate
float
The tax rate to be applied to investment earnings. If excluded, defaults to 0.
inflation_rate
float
The inflation rate to be applied to deposits. If excluded, defaults to 0.
account_ids
array[UUID]
The ID(s) of the Nucleus account(s) used to derive initial_balance. If initial_balance is not provided, we will try to use account_ids to derive this value instead.
create_log
boolean
If true, a record of this Proton request URL, request body, response body, and Nucleus UUID(s), where applicable, will be stored in Electron as an audit log, and the resulting audit_log_id will be returned in the Proton response. Defaults to false.

Example Response

{
    "ending_balance": 28465.18,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 10000
        },
        "1": {
            "period_earnings": 134,
            "period_contribution": 3264,
            "period_withdrawal": 0,
            "cumulative_earnings": 134,
            "cumulative_contributions": 3264,
            "cumulative_withdrawals": 0,
            "ending_balance": 13398
        },
        "2": {
            "period_earnings": 224.42,
            "period_contribution": 3329.28,
            "period_withdrawal": 0,
            "cumulative_earnings": 358.42,
            "cumulative_contributions": 6593.28,
            "cumulative_withdrawals": 0,
            "ending_balance": 16951.7
        },
        "3": {
            "period_earnings": 283.94,
            "period_contribution": 3395.87,
            "period_withdrawal": 0,
            "cumulative_earnings": 642.36,
            "cumulative_contributions": 9989.15,
            "cumulative_withdrawals": 0,
            "ending_balance": 20631.5
        },
        "4": {
            "period_earnings": 345.58,
            "period_contribution": 3463.78,
            "period_withdrawal": 0,
            "cumulative_earnings": 987.94,
            "cumulative_contributions": 13452.93,
            "cumulative_withdrawals": 0,
            "ending_balance": 24440.86
        },
        "5": {
            "period_earnings": 491.26,
            "period_contribution": 3533.06,
            "period_withdrawal": 0,
            "cumulative_earnings": 1479.2,
            "cumulative_contributions": 16985.99,
            "cumulative_withdrawals": 0,
            "ending_balance": 28465.18
        }
    }
}

RESPONSE

Field Description
ending_balance The ending balance of the investment, represented in today’s dollars.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings
      
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      period_contribution
      
The deposit made for this period.
      period_withdrawal
      
The withdrawal made for this period.
      cumulative_earnings
      
The cumulative investment earnings made up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.
audit_log_id The unique id of the audit log record created in Electron. Only returned when create_log = true.

NUCLEUS DATA DEPENDENCIES

Budget Analysis

Budget Calculator analyzes a client’s spending patterns against pre-defined budgets over time. This is useful to gain a deeper understanding of how closely a client follows a particular budget. A breakdown of each underlying budget item also provides helpful data to aid clients in staying on track and achieving their budgetary goals.

HTTP REQUEST

POST /budget_calculator

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
          "budget_id": "790c936b-015d-4d8a-82ed-434a4bbc13e8",
          "as_of_date": "2016-12-22",
          "lookback_periods": 3
      }' "https://api.hydrogenplatform.com/proton/v1/budget_calculator"
PersonalFinancialManagementApi personalFinancialManagementApi = new PersonalFinancialManagementApi();
BudgetCalculatorRequest budgetCalculatorRequest =  new BudgetCalculatorRequest();
budgetCalculatorRequest.setBudgetId(UUID.fromString("5033e1d2-afed-4428-ac20-6fecefccb4c3"));
budgetCalculatorRequest.setScope(BudgetCalculatorRequest.ScopeEnum.ALL);
budgetCalculatorRequest.setTransactionStatusScope(Arrays.asList("completed",
        "pending"));
budgetCalculatorRequest.setCurrencyConversion("USD");
budgetCalculatorRequest.asOfDate(LocalDate.parse("2019-12-31"));
budgetCalculatorRequest.setLookbackPeriods(6);
budgetCalculatorRequest.setShowBudgetTrack(TRUE);
budgetCalculatorRequest.setShowAverageSpend(TRUE);
budgetCalculatorRequest.setOnlyCleansed(TRUE);
Map<String, Object> budgetCalculatorResponse = null;
try {
    budgetCalculatorResponse = personalFinancialManagementApi
            .budgetCalculator(budgetCalculatorRequest);
    System.out.println(budgetCalculatorResponse);
} catch (ApiException e) {
    e.printStackTrace();
}
api_instance = proton_api.PersonalFinancialManagementApi(proton_api.ApiClient(configuration))
budget_calculator_request = proton_api.BudgetCalculatorRequest(
    budget_id="5033e1d2-afed-4428-ac20-6fecefccb4c3", scope='all', transaction_status_scope=["completed",
                                                                                             "pending"],
    currency_conversion='USD', as_of_date="2019-12-31", lookback_periods=6, show_budget_track=True, show_average_spend=True,
    only_cleansed=True
)

try:
    # PersonalFinancialManagementApi - Budget Calculator
    api_response = api_instance.budget_calculator(budget_calculator_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling PersonalFinancialManagementApi->budget_calculator: %s\n" % e)
api_instance = ProtonApi::PersonalFinancialManagementApi.new
budgetCalculatorRequest= ProtonApi::BudgetCalculatorRequest.new
begin
  budgetCalculatorRequest.budget_id = "5033e1d2-afed-4428-ac20-6fecefccb4c3"
  budgetCalculatorRequest.scope = "all"
  budgetCalculatorRequest.transaction_status_scope = ["completed", "pending"]
  budgetCalculatorRequest.currency_conversion = "USD"
  budgetCalculatorRequest.as_of_date = "2020-12-31"
  budgetCalculatorRequest.lookback_periods = 6
  budgetCalculatorRequest.show_budget_track = true
  budgetCalculatorRequest.show_average_spend = true
  budgetCalculatorRequest.only_cleansed = true
  budgetCalculatorResponse = api_instance.budget_calculator(budgetCalculatorRequest)
  p budgetCalculatorResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling budget_Calculator_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\PersonalFinancialManagementApi(
    new GuzzleHttp\Client(),
    $config
);
$budgetCalculatorRequest = new com\hydrogen\proton\Model\BudgetCalculatorRequest();
try {
    $budgetCalculatorRequest->setbudgetid("5033e1d2-afed-4428-ac20-6fecefccb4c3");
    $budgetCalculatorRequest->setScope("all");
    $budgetCalculatorRequest->setTransactionStatusScope(array("completed", "pending"));
    $budgetCalculatorRequest->setasofdate("2020-12-31");
    $budgetCalculatorRequest->setCurrencyConversion("USD");
    $budgetCalculatorRequest->setlookbackperiods(6);
    $budgetCalculatorRequest->setShowBudgetTrack(true);
    $budgetCalculatorRequest->setShowAverageSpend(true);
    $budgetCalculatorRequest->setOnlyCleansed(true);
    $result = $apiInstance->budgetCalculator($budgetCalculatorRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PersonalFinancialManagementAPI->budgetCalculator: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.PersonalFinancialManagementApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.PersonalFinancialManagementApi();
    var budgetCalculatorRequest= new HydrogenProtonApi.BudgetCalculatorRequest();
    budgetCalculatorRequest.budget_id = "713ab6c0-6861-474a-9ed0-f02fec3e1137";
    budgetCalculatorRequest.transactionStatusScope = ["completed", "pending"];
    budgetCalculatorRequest.scope = "all";
    budgetCalculatorRequest.currencyConversion = "USD";
    budgetCalculatorRequest.showBudgetTrack = true;
    budgetCalculatorRequest.showAverageSpend = true;
    budgetCalculatorRequest.onlyCleansed = true;
    budgetCalculatorRequest.as_of_date = "2019-12-31";
    budgetCalculatorRequest.lookback_periods = 6;
    api.budgetCalculator(budgetCalculatorRequest, callback)

ARGUMENTS

Parameter Description
budget_id
UUID, conditional requirement
The ID of the Nucleus Budget. Please note that this service is not compatible with budgets that have a frequency_unit of semi-monthly. Required if budget_details is not provided.
transaction_status_scope
array[string]
If populated, only transactions whose status matches one of the array values are considered in the analysis. Defaults to null, meaning all transactions are considered regardless of the status.
currency_conversion
string
The alphabetic currency code used to conduct the analysis, limited to 3 characters. Records will be converted from their original currency to the one indicated here. Conversions are supported both to and from the following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See Currencies. Only applicable when a budget_id is provided.
as_of_date
date
Reference date of the analysis. Calculations will run through the earlier of this date and budget.end_date as defined in Nucleus. Defaults to today’s date.
lookback_periods
integer
Number of lookback periods to analyze. Each period length is defined by the combination of budget.frequency and budget.frequency_unit as defined in Nucleus, and period dates are set on a discrete calendar basis. A value of 0 would reflect only the current (partial) period containing as_of_date. Defaults to 1.
show_budget_track
boolean
If true, return the budget_track response, an analysis of spending versus budget for each budget period. Defaults to true.
show_average_spend
boolean
If true, return the average_spend response, an analysis of average spending values for each budget component and in total across the time periods analyzed. Defaults to false.
only_cleansed
boolean
If true, only Portfolio Transactions with the is_cleansed parameter set to true will be considered. Defaults to false.
budget_details
map, conditional requirement
Raw budget details that can be provided in place of a budget_id. Allows the analysis to be run without creating a Budget in Nucleus. This field is required if budget_id is not provided.
      client_id
      UUID, required
The ID of the Nucleus Client the budget belongs to.
      account_id
      UUID
The ID of the Nucleus Account associated with the budget.
      frequency_unit
      string, required
Frequency of the budget. Value may be daily, weekly, bi-weekly, monthly, quarterly, or annually.
      frequency
      integer
Number of frequency_unit between each budget. For example, if the frequency_unit is weekly and the frequency is 2, this means the budget occurs every two weeks. Default is 1.
      currency_code
      string
The alphabetic currency code used to conduct the analysis, limited to 3 characters. Only records with this currency code will be considered. Defaults to USD. See Currencies.
      total_value
      float, conditional requirement
Total value of the budget. Required if budget is not provided.
      budget
      array[map], conditional requirement
List of budget components and their values. Required if total_value is not provided.
            category
            string, required
Category of the budget component.
            subcategory
            string
Subcategory of the budget component.
            value
            float, required
Value of the budget component.
      start_date
      date
The start date for the budget. If not provided, defaults to today’s date.
      end_date
      date
The end date for the budget.

Example Response

{
    "currency_code": "USD",
    "budget_track": [
        {
            "period_start": "2016-10-01",
            "period_end": "2016-10-31",
            "total_funds_budgeted": 100.0,
            "total_funds_spent": 56.51,
            "total_funds_remaining": 43.49,
            "budget_components": [
                {
                    "category": "Food & Dining",
                    "subcategory": "Alcohol & Bars",
                    "funds_budgeted": 50.0,
                    "funds_spent": 0,
                    "funds_remaining": 50.0
                },
                {
                    "category": "Health & Fitness",
                    "subcategory": "Sports",
                    "funds_budgeted": 50.0,
                    "funds_spent": 56.51,
                    "funds_remaining": -6.51
                }
            ]
        },
        {
            "period_start": "2016-11-01",
            "period_end": "2016-11-30",
            "total_funds_budgeted": 100.0,
            "total_funds_spent": 0,
            "total_funds_remaining": 100.0,
            "budget_components": [
                {
                    "category": "Food & Dining",
                    "subcategory": "Alcohol & Bars",
                    "funds_budgeted": 50.0,
                    "funds_spent": 0,
                    "funds_remaining": 50.0
                },
                {
                    "category": "Health & Fitness",
                    "subcategory": "Sports",
                    "funds_budgeted": 50.0,
                    "funds_spent": 0,
                    "funds_remaining": 50.0
                }
            ]
        },
        {
            "period_start": "2016-12-01",
            "period_end": "2016-12-22",
            "total_funds_budgeted": 100.0,
            "total_funds_spent": 284.77,
            "total_funds_remaining": -184.77,
            "budget_components": [
                {
                    "category": "Food & Dining",
                    "subcategory": "Alcohol & Bars",
                    "funds_budgeted": 50.0,
                    "funds_spent": 284.77,
                    "funds_remaining": -234.77
                },
                {
                    "category": "Health & Fitness",
                    "subcategory": "Sports",
                    "funds_budgeted": 50.0,
                    "funds_spent": 0,
                    "funds_remaining": 50.0
                }
            ]
        }
    ]
}

RESPONSE

Field Description
currency_code Currency code associated with monetary response values.
budget_track Analysis of spending versus budget for each budget period
      period_start Start date of the budget period.
      period_end End date of the budget period.
      total_funds_budgeted Total amount of funds originally budgeted.
      total_funds_spent Total amount of funds spent.
      total_funds_remaining Total amount of funds remaining, i.e. the delta between total_funds_budgeted and total_funds_spent.
      percent_spent Total percent of funds spent.
      percent_remaining Total percent of funds remaining.
      budget_components Details for each item defined under the budget.
            category
      
The budget component’s spending category.
            subcategory
      
The budget component’s spending subcategory.
            funds_budgeted
      
Amount of funds originally budgeted.
            funds_spent
      
Amount of funds spent.
            funds_remaining
      
Amount of funds remaining, i.e. the delta between funds_budgeted and funds_spent.
            percent_spent
      
Percent of funds spent.
            percent_remaining
      
Percent of funds remaining.
average_spend Analysis of average spending values for each budget component and in total across the time periods analyzed.
      total Total average amount of funds spent.
      budget_components Details of average spending values for each budget component.
            category
      
Category of the budget component.
            subcategory
      
Subcategory of the budget component.
            value
      
Average amount of funds spent for the budget component.

NUCLEUS DATA DEPENDENCIES

Cash Flow Analysis

Cash Flow Analysis provides a benchmarked view of a client’s cash flows over time, including income, spending, and net cash flow values. This tool is useful for charting cash flows trends over time, as well as for displaying helpful details about a client’s spending habits. Tracking these cash flow values against a benchmark time period allows for insight into how the client’s cash flow situation is changing relative to previous behavior.

HTTP REQUEST

Example Request

POST /cash_flow_analysis

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "a32a48f7-d30e-489b-9d2b-576a3939343f",
        "currency_code": "USD",
        "start_date": "2015-06-15",
        "end_date": "2015-06-17",
        "show_history": true,
        "show_spending_details": true,
        "show_income_details": true,
        "only_cleansed": true
      }' "https://api.hydrogenplatform.com/proton/v1/cash_flow_analysis"
PersonalFinancialManagementApi personalFinancialManagementApi = new PersonalFinancialManagementApi();
CashFlowAnalysisRequest cashFlowAnalysisRequest = new CashFlowAnalysisRequest();
cashFlowAnalysisRequest.setClientId(UUID.fromString("dd184bee-747d-4024-aafc-fe9864113f09"));
cashFlowAnalysisRequest.setScope(CashFlowAnalysisRequest.ScopeEnum.ALL);
cashFlowAnalysisRequest.setTransactionStatusScope(Arrays.asList("completed",
        "pending"));
cashFlowAnalysisRequest.setCurrencyCode("USD");
cashFlowAnalysisRequest.setCurrencyConversion("USD");
cashFlowAnalysisRequest.setStartDate(LocalDate.parse("2019-07-01"));
cashFlowAnalysisRequest.setEndDate(LocalDate.parse("2019-12-31"));
cashFlowAnalysisRequest.setBenchmarkStartDate(LocalDate.parse("2019-01-01"));
cashFlowAnalysisRequest.setBenchmarkEndDate(LocalDate.parse("2019-06-30"));
cashFlowAnalysisRequest.setShowHistory(TRUE);
cashFlowAnalysisRequest.setShowSpendingDetails(TRUE);
cashFlowAnalysisRequest.setShowIncomeDetails(TRUE);
cashFlowAnalysisRequest.setOnlyCleansed(TRUE);
Map<String, Object> cashFlowAnalysisResponse = null;
try {
    cashFlowAnalysisResponse = personalFinancialManagementApi
            .cashFlowAnalysis(cashFlowAnalysisRequest);
    System.out.println(cashFlowAnalysisResponse);
} catch (ApiException e) {
    e.printStackTrace();
}
api_instance = proton_api.PersonalFinancialManagementApi(proton_api.ApiClient(configuration))
cash_flow_analysis_request = proton_api.CashFlowAnalysisRequest(
    client_id='dd184bee-747d-4024-aafc-fe9864113f09', scope='all', transaction_status_scope=["completed",
                                                                                             "pending"],
    currency_code="USD", currency_conversion="USD", start_date="2019-07-01", end_date="2019-12-31", benchmark_start_date="2019-01-01",
    benchmark_end_date="2019-06-30", show_history=True, show_spending_details=True, show_income_details=True, only_cleansed=True
)
try:
    # PersonalFinancialManagementApi - Cash Flow Analysis
    api_response = api_instance.cash_flow_analysis(cash_flow_analysis_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling PersonalFinancialManagementApi->cash_flow_analysis: %s\n" % e)
api_instance = ProtonApi::PersonalFinancialManagementApi.new
cashFlowAnalysisRequest= ProtonApi::CashFlowAnalysisRequest.new
begin
  cashFlowAnalysisRequest.client_id ="dd184bee-747d-4024-aafc-fe9864113f09"
  cashFlowAnalysisRequest.scope = "all"
  cashFlowAnalysisRequest.transaction_status_scope = ["completed", "pending"]
  cashFlowAnalysisRequest.start_date ="2019-07-01"
  cashFlowAnalysisRequest.end_date="2019-12-31"
  cashFlowAnalysisRequest.benchmark_start_date = "2019-01-01"
  cashFlowAnalysisRequest.benchmark_end_date = "2020-08-10"
  cashFlowAnalysisRequest.currency_code="USD"
  cashFlowAnalysisRequest.currency_conversion = "USD"
  cashFlowAnalysisRequest.show_history=true
  cashFlowAnalysisRequest.show_spending_details=true
  cashFlowAnalysisRequest.show_income_details=true
  cashFlowAnalysisRequest.only_cleansed = true
  cashFlowAnalysisResponse = api_instance.cash_flow_analysis(cashFlowAnalysisRequest)
  p cashFlowAnalysisResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling cash_FLow_Analysis_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\PersonalFinancialManagementApi(
    new GuzzleHttp\Client(),
    $config
);
$cashFlowAnalysisRequest = new com\hydrogen\proton\Model\CashFlowAnalysisRequest();
try {
    $cashFlowAnalysisRequest->setClientId("dd184bee-747d-4024-aafc-fe9864113f09");
    $cashFlowAnalysisRequest->setStartDate("2020-07-01");
    $cashFlowAnalysisRequest->setScope("all");
    $cashFlowAnalysisRequest->setTransactionStatusScope(array("completed", "pending"));
    $cashFlowAnalysisRequest->setEndDate("2020-08-31");
    $cashFlowAnalysisRequest->setBenchmarkStartDate("2019-01-01");
    $cashFlowAnalysisRequest->setBenchmarkEndDate("2019-06-30");
    $cashFlowAnalysisRequest->setShowHistory(false);
    $cashFlowAnalysisRequest->setShowSpendingDetails(true);
    $cashFlowAnalysisRequest->setShowIncomeDetails(true);
    $cashFlowAnalysisRequest->setCurrencyCode("USD");
    $cashFlowAnalysisRequest->setCurrencyConversion("USD");
    $cashFlowAnalysisRequest->setOnlyCleansed(true);
    $result = $apiInstance->cashFlowAnalysis($cashFlowAnalysisRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PersonalFinancialManagementApi->cashFlowAnalysis: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.PersonalFinancialManagementApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.PersonalFinancialManagementApi();
    var cashflowanalysisRequest= new HydrogenProtonApi.CashFlowAnalysisRequest();
    cashflowanalysisRequest.client_id="acfec2ee-3816-4485-a126-7def389cac9f";
    cashflowanalysisRequest.scope = "all";
    cashflowanalysisRequest.transactionStatusScope = ["completed", "pending"];
    cashflowanalysisRequest.currency_code="USD"
    cashflowanalysisRequest.currencyConversion = "USD";
    cashflowanalysisRequest.start_date= "2020-01-01";
    cashflowanalysisRequest.end_date= "2020-08-31";
    cashflowanalysisRequest.benchmark_start_date = "2020-10-10";
    cashflowanalysisRequest.benchmark_end_date = "2020-12-10";
    cashflowanalysisRequest.show_history= "true";
    cashflowanalysisRequest.show_spending_details= "true";
    cashflowanalysisRequest.show_income_details= "true";
    cashflowanalysisRequest.onlyCleansed = true;
    api.cashFlowAnalysis(cashflowanalysisRequest, callback)

ARGUMENTS

Parameter Description
client_id
UUID, conditional requirement
The ID of a Nucleus client whose data to analyze. Conditionally required if one of household_id, account_ids is not provided.
household_id
UUID, conditional requirement
The ID of a Nucleus household whose data to analyze. Conditionally required if one of client_id, account_ids is not provided.
account_ids
array[UUID], conditional requirement
ID(s) of the Nucleus Account(s) whose data to analyze. Conditionally required if one of client_id, household_id is not provided.
transaction_status_scope
array[string]
If populated, only transactions whose status matches one of the array values are included in the analysis. Defaults to null, meaning all transactions are included regardless of the status.
currency_code
string
The alphabetic currency code used to conduct the analysis, limited to 3 characters. Only records with this currency code will be considered. Defaults to USD if currency_conversion is not provided. If currency_conversion is provided, all origin currencies will be considered by default. See Currencies.
currency_conversion
string
The alphabetic currency code used to conduct the analysis, limited to 3 characters. Records will be converted from their original currency to the one indicated here. Conversions are supported both to and from the following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See Currencies.
start_date
date
Start date of the analysis period. Defaults to the earliest available transaction date.
end_date
date
End date of the analysis period. Defaults to the latest available transaction date.
benchmark_start_date
date
Start date of the benchmark analysis period. Default values for benchmark_start_date and benchmark_end_date are based on the difference between start_date and end_date. For example, if start_date and end_date are 2016-06-15 and 2016-06-17, respectively, benchmark_start_date and benchmark_end_date default to 2016-06-12 and 2016-06-14, respectively.
benchmark_end_date
date
End date of the benchmark analysis period. Default values for benchmark_start_date and benchmark_end_date are based on the difference between start_date and end_date. For example, if start_date and end_date are 2016-06-15 and 2016-06-17, respectively, benchmark_start_date and benchmark_end_date default to 2016-06-12 and 2016-06-14, respectively.
show_history
boolean
If true, return a daily history of the client’s cash flow details within the specified date range. Defaults to false.
show_spending_details
boolean
If true, return advanced spending details including breakdowns by category and by merchant as well as any outlying expenditures. Outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 threshold. Defaults to false.
show_income_details
boolean
If true, return advanced income details including breakdowns by category and by merchant as well as any outlying inflows. Outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 threshold. Defaults to false.
only_cleansed
boolean
If true, only Portfolio Transactions with the is_cleansed parameter set to true will be considered. Defaults to false.

Example Response

{
    "currency_code": "USD",
    "income_summary": {
        "total": 0.0,
        "benchmark_total": 0.0,
        "change": {
            "value": 0.0,
            "percentage": null
        }
    },
    "spending_summary": {
        "total": 266.35,
        "benchmark_total": 460.96,
        "change": {
            "value": -194.61,
            "percentage": -0.4222
        }
    },
    "net_summary": {
        "total": -266.35,
        "benchmark_total": -460.96,
        "change": {
            "value": 194.61,
            "percentage": -0.4222
        }
    },
    "history": [
        {
            "date": "2015-06-15",
            "period_income": 0.0,
            "period_spending": 0.0,
            "period_net": 0.0,
            "cumulative_income": 0.0,
            "cumulative_spending": 0.0,
            "cumulative_net": 0.0
        },
        {
            "date": "2015-06-16",
            "period_income": 0.0,
            "period_spending": 0.0,
            "period_net": 0.0,
            "cumulative_income": 0.0,
            "cumulative_spending": 0.0,
            "cumulative_net": 0.0
        },
        {
            "date": "2015-06-17",
            "period_income": 0.0,
            "period_spending": 266.35,
            "period_net": -266.35,
            "cumulative_income": 0.0,
            "cumulative_spending": 266.35,
            "cumulative_net": -266.35
        }
    ],
    "benchmark_history": [
        {
            "date": "2015-06-12",
            "period_income": 0.0,
            "period_spending": 0.0,
            "period_net": 0.0,
            "cumulative_income": 0.0,
            "cumulative_spending": 0.0,
            "cumulative_net": 0.0
        },
        {
            "date": "2015-06-13",
            "period_income": 0.0,
            "period_spending": 270.96,
            "period_net": -270.96,
            "cumulative_income": 0.0,
            "cumulative_spending": 270.96,
            "cumulative_net": -270.96
        },
        {
            "date": "2015-06-14",
            "period_income": 0.0,
            "period_spending": 190.0,
            "period_net": -190.0,
            "cumulative_income": 0.0,
            "cumulative_spending": 460.96,
            "cumulative_net": -460.96
        }
    ],
    "spending_details": {
        "by_category": [
            {
                "category": "Food & Dining",
                "value": 266.35,
                "benchmark_value": 0.0,
                "change": {
                    "value": 266.35,
                    "percentage": null
                },
                "weight": 1.0,
                "benchmark_weight": 0.0,
                "subcategories": [
                    {
                        "subcategory": "Restaurants",
                        "value": 266.35,
                        "benchmark_value": 0.0,
                        "change": {
                            "value": 266.35,
                            "percentage": null
                        },
                        "weight": 1.0,
                        "benchmark_weight": 0.0
                    }
                ]
            },
            {
                "category": "Business Services",
                "value": 0.0,
                "benchmark_value": 270.96,
                "change": {
                    "value": -270.96,
                    "percentage": -1.0
                },
                "weight": 0.0,
                "benchmark_weight": 0.5878,
                "subcategories": [
                    {
                        "subcategory": "Legal",
                        "value": 0.0,
                        "benchmark_value": 270.96,
                        "change": {
                            "value": -270.96,
                            "percentage": -1.0
                        },
                        "weight": 0.0,
                        "benchmark_weight": 1.0
                    }
                ]
            },
            {
                "category": "Health & Fitness",
                "value": 0.0,
                "benchmark_value": 190.0,
                "change": {
                    "value": -190.0,
                    "percentage": -1.0
                },
                "weight": 0.0,
                "benchmark_weight": 0.4122,
                "subcategories": [
                    {
                        "subcategory": "Health Insurance",
                        "value": 0.0,
                        "benchmark_value": 190.0,
                        "change": {
                            "value": -190.0,
                            "percentage": -1.0
                        },
                        "weight": 0.0,
                        "benchmark_weight": 1.0
                    }
                ]
            }
        ],
        "by_merchant": [
            {
                "merchant": "Isdom",
                "value": 266.35,
                "benchmark_value": 0.0,
                "change": {
                    "value": 266.35,
                    "percentage": null
                },
                "weight": 1.0,
                "benchmark_weight": 0.0
            },
            {
                "merchant": "Blackzim",
                "value": 0.0,
                "benchmark_value": 270.96,
                "change": {
                    "value": -270.96,
                    "percentage": -1.0
                },
                "weight": 0.0,
                "benchmark_weight": 0.5878
            },
            {
                "merchant": "Geojaycare",
                "value": 0.0,
                "benchmark_value": 190.0,
                "change": {
                    "value": -190.0,
                    "percentage": -1.0
                },
                "weight": 0.0,
                "benchmark_weight": 0.4122
            }
        ],
        "outliers": []
    },
    "income_details": {
        "by_category": [],
        "by_merchant": [],
        "outliers": []
    }
}

RESPONSE

Field Description
currency_code Currency code associated with monetary response values.
income_summary List of the total income values and the calculated delta between overall and benchmark.
      total Total cash inflows over the trend period.
      benchmark_total Total cash inflows over the benchmark trend period.
      change Difference in total cash inflows between the trend period and the benchmark trend period.
            value Value change as of the analysis end date.
            percentage Percentage change as of the analysis end date.
spending_summary List of the total spending values and the calculated delta between overall and benchmark.
      total Total cash outflows over the trend period.
      benchmark_total Total cash outflows over the benchmark trend period.
      change Difference in total cash outflows between the trend period and the benchmark trend period.
            value Value change as of the analysis end date.
            percentage Percentage change as of the analysis end date.
net_summary List of the total net values and the calculated delta between overall and benchmark.
      total Total net cash flows over the trend period.
      benchmark_total Total net cash flows over the benchmark trend period.
      change Difference in total net cash flows between the trend period and the benchmark trend period.
            value Value change as of the analysis end date.
            percentage Percentage change as of the analysis end date.
history List of income, spending and net values calculated by day.
      date Date of the spending history record.
      period_income Cash inflows during the period.
      period_spending Cash outflows during the period.
      period_net Net cash inflows (outflows) during the period.
      cumulative_income Cumulative cash inflows up to and including this period.
      cumulative_spending Cumulative cash outflows up to and including this period.
      cumulative_net Cumulative net cash inflows (outflows) up to and including this period.
benchmark_history List of benchmark income, spending and net values calculated by day.
      date Date of benchmark spending history record.
      period_income Cash inflows during the period.
      period_spending Cash outflows during the period.
      period_net Net cash inflows (outflows) during the period.
      cumulative_income Cumulative cash inflows up to and including this period.
      cumulative_spending Cumulative cash outflows up to and including this period.
      cumulative_net Cumulative net cash inflows (outflows) up to and including this period.
spending_details List of spending information separated by categories and merchants.
      by_category List of spending information separated by categories and their relative subcategories.
            category Spending category as defined in the Nucleus transactions.
            value Sum of all transactions over the period for the given category.
            benchmark_value Sum of all transactions over the benchmark period for the given category.
            change Difference in total net cash outflows per category between the trend period and the benchmark trend period.
                  value Value change as of the analysis end date.
                  percentage Percentage change as of the analysis end date.
            weight The proportion of all spending over the period related to this category.
            benchmark_weight The proportion of all spending over the benchmark period related to this category.
            subcategories List of spending subcategory as defined in the Nucleus transactions.
                  subcategory Spending category as defined in the Nucleus transactions.
                  value Sum of all transactions over the period for the given subcategory.
                  benchmark_value Sum of all transactions over the benchmark period for the given subcategory.
                  change Difference in total net cash outflows per subcategory between the trend period and the benchmark trend period.
                        value Value change as of the analysis end date.
                        percentage Percentage change as of the analysis end date.
                  weight The proportion of all spending over the period related to this subcategory.
                  benchmark_weight The proportion of all spending over the benchmark period related to this subcategory.
      by_merchant List of spending information separated by merchant.
            merchant Merchant name as defined in the Nucleus transactions.
            value Sum of all transactions over the period for the given merchant.
            benchmark_value Sum of all transactions over the benchmark period for the given merchant.
            change Difference in total net cash outflows per merchant between the trend period and the benchmark trend period.
                        value Value change as of the analysis end date.
                        percentage Percentage change as of the analysis end date.
            weight The proportion of all spending over the period related to this merchant.
            benchmark_weight The proportion of all spending over the benchmark period related to this merchant.
      outliers List of spending transactions whose amount is beyond 2.5 median absolute deviations from the median of all transaction amounts. Each entry represent a raw transaction record from Nucleus. Please see Nucleus Portfolio Transaction for more details on underlying fields.
income_details List of income information separated by categories and merchants.
      by_category List of income information separated by categories and their relative subcategories.
            category Income category as defined in the Nucleus transactions.
            value Sum of all transactions over the period for the given category.
            benchmark_value Sum of all transactions over the benchmark period for the given category.
            change Difference in total net cash inflows per category between the trend period and the benchmark trend period.
                  value Value change as of the analysis end date.
                  percentage Percentage change as of the analysis end date.
            weight The proportion of all income over the period related to this category.
            benchmark_weight The proportion of all income over the benchmark period related to this category.
            subcategories List of income subcategory as defined in the Nucleus transactions.
                  subcategory Income category as defined in the Nucleus transactions.
                  value Sum of all transactions over the period for the given subcategory.
                  benchmark_value Sum of all transactions over the benchmark period for the given subcategory.
                  change Difference in total net cash inflows per subcategory between the trend period and the benchmark trend period.
                        value Value change as of the analysis end date.
                        percentage Percentage change as of the analysis end date.
                  weight The proportion of all income over the period related to this subcategory.
                  benchmark_weight The proportion of all income over the benchmark period related to this subcategory.
      by_merchant List of income information separated by merchant.
            merchant Merchant name as defined in the Nucleus transactions.
            value Sum of all transactions over the period for the given merchant.
            benchmark_value Sum of all transactions over the benchmark period for the given merchant.
            change Difference in total net cash inflows per merchant between the trend period and the benchmark trend period.
                        value Value change as of the analysis end date.
                        percentage Percentage change as of the analysis end date.
            weight The proportion of all income over the period related to this merchant.
            benchmark_weight The proportion of all income over the benchmark period related to this merchant.
      outliers List of income transactions whose amount is beyond 2.5 median absolute deviations from the median of all transaction amounts. Each entry represent a raw transaction record from Nucleus. Please see Nucleus Portfolio Transaction for more details on underlying fields.

NUCLEUS DATA DEPENDENCIES

Spending Analysis

A detailed and configurable analysis of spending across various entities.

HTTP REQUEST

POST /spending_analysis

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "business_ids": [
            "b589ad60-86ad-42a0-b4fc-4e9b1587ff8e"
        ],
        "currency_code": "USD",
        "card_status_scope": [
            "activated"
        ],
        "transaction_status_scope": [
            "completed",
            "pending"
        ],
        "transaction_category_scope": [
            "e594f949-6f92-11eb-922d-124ab2ff7f93"
        ],
        "merchant_scope": [
            "0a7b62b4-54f3-4cef-afd9-c695d1d28740"
        ],
        "frequency_unit": "monthly",
        "frequency": 1,
        "start_date": "2021-02-01",
        "end_date": "2021-04-26",
        "show_by_period": true,
        "show_by_category": true,
        "show_by_merchant": true,
        "only_cleansed": false,
        "only_active_clients": false
      }' "https://api.hydrogenplatform.com/proton/v1/spending_analysis"
PersonalFinancialManagementApi personalFinancialManagementApi = new PersonalFinancialManagementApi();
SpendingAnalysisRequest spendingAnalysisRequest = new SpendingAnalysisRequest();
spendingAnalysisRequest.setBusinessIds(Arrays.<UUID>asList(
        UUID.fromString("9301b99f-a776-46aa-aeeb-9cefaf3e67c0")));
spendingAnalysisRequest.setCurrencyCode("USD");
spendingAnalysisRequest.setScope(SpendingAnalysisRequest.ScopeEnum.ALL);
spendingAnalysisRequest.setCardStatusScope(Arrays.asList("activated"));
spendingAnalysisRequest.setTransactionStatusScope(Arrays.asList(
        "completed",
        "pending"
));
spendingAnalysisRequest.setFrequencyUnit(SpendingAnalysisRequest.FrequencyUnitEnum.MONTHLY);
spendingAnalysisRequest.setFrequency(1);
spendingAnalysisRequest.setStartDate(LocalDate.parse("2021-02-01"));
spendingAnalysisRequest.setEndDate(LocalDate.parse("2021-04-26"));
spendingAnalysisRequest.setShowByPeriod(TRUE);
spendingAnalysisRequest.setShowByCategory(TRUE);
spendingAnalysisRequest.setShowByMerchant(TRUE);
spendingAnalysisRequest.setOnlyCleansed(TRUE);
spendingAnalysisRequest.setOnlyActiveClients(TRUE);
try {
    Map<String, Object> spendingAnalysisResponse = personalFinancialManagementApi
            .spendingAnalysis(spendingAnalysisRequest);
    System.out.println(spendingAnalysisResponse);
} catch (ApiException e) {
    e.printStackTrace();
}
api_instance = proton_api.PersonalFinancialManagementApi(proton_api.ApiClient(configuration))
spending_analysis_request = proton_api.SpendingAnalysisRequest(
    business_ids=["9301b99f-a776-46aa-aeeb-9cefaf3e67c0"], currency_code="USD", scope='all', card_status_scope=['activated'],
    transaction_status_scope=["completed",
                              "pending"],
    frequency_unit='monthly', frequency=1, start_date="2021-02-01", end_date="2021-04-26", show_by_period=True, show_by_category=True, show_by_merchant=True,
    only_cleansed=True, only_active_clients=True
)
try:
    # PersonalFinancialManagementApi - Spending Analysis
    api_response = api_instance.spending_analysis(spending_analysis_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling PersonalFinancialManagementApi->spending_analysis: %s\n" % e)
api_instance = ProtonApi::PersonalFinancialManagementApi.new
spendingAnalysisRequest = ProtonApi::SpendingAnalysisRequest.new
begin
  spendingAnalysisRequest.business_ids = ["9301b99f-a776-46aa-aeeb-9cefaf3e67c0"]
  spendingAnalysisRequest.currency_code = "USD"
  spendingAnalysisRequest.scope = "all"
  spendingAnalysisRequest.card_status_scope = ["activated"]
  spendingAnalysisRequest.transaction_status_scope = ["completed", "pending"]
  spendingAnalysisRequest.frequency_unit = "monthly"
  spendingAnalysisRequest.frequency = 1
  spendingAnalysisRequest.start_date = "2020-10-10"
  spendingAnalysisRequest.end_date = "2021-01-10"
  spendingAnalysisRequest.show_by_category = true
  spendingAnalysisRequest.show_by_period = true
  spendingAnalysisRequest.show_by_merchant = true
  spendingAnalysisRequest.only_cleansed = true
  spendingAnalysisRequest.only_active_clients = true
  spendingAnalysisResponse = api_instance.spending_analysis(spendingAnalysisRequest)
  p spendingAnalysisResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling spending_analysis #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\PersonalFinancialManagementApi(
    new GuzzleHttp\Client(),
    $config
);
$spendingAnalysisRequest = new com\hydrogen\proton\Model\SpendingAnalysisRequest();
try {
    $spendingAnalysisRequest->setBusinessIds(array("9301b99f-a776-46aa-aeeb-9cefaf3e67c0"));
    $spendingAnalysisRequest->setCurrencyCode("USD");
    $spendingAnalysisRequest->setScope("all");
    $spendingAnalysisRequest->setCardStatusScope(array('9301b99f-a776-46aa-aeeb-9cefaf3e67c0'));
    $spendingAnalysisRequest->setTransactionStatusScope(array("completed", "pending"));
    $spendingAnalysisRequest->setFrequency(1);
    $spendingAnalysisRequest->setFrequencyUnit("monthly");
    $spendingAnalysisRequest->setStartDate("2021-02-01");
    $spendingAnalysisRequest->setEndDate("2021-04-26");
    $spendingAnalysisRequest->setShowByPeriod(true);
    $spendingAnalysisRequest->setShowByCategory(true);
    $spendingAnalysisRequest->setShowByMerchant(true);
    $spendingAnalysisRequest->setOnlyCleansed(true);
    $spendingAnalysisRequest->setOnlyActiveClients(true);

    $result = $apiInstance->spendingAnalysis($spendingAnalysisRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PersonalFinancialManagementAPI->recurringTransactionAnalysis: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.PersonalFinancialManagementApi();
  var callback = function(error, data, response) {
      if (error) {
          console.error(error);
      } else {
          console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
      }
  };
  var api = new HydrogenProtonApi.PersonalFinancialManagementApi();
      var spendinganalysisRequest= new HydrogenProtonApi.SpendingAnalysisRequest();
      spendinganalysisRequest.businessIds = ["9301b99f-a776-46aa-aeeb-9cefaf3e67c0"];
      spendinganalysisRequest.currency_code = "USD";
      spendinganalysisRequest.scope = "all";
      spendinganalysisRequest.card_status_scope = ["activated"];
      spendinganalysisRequest.transaction_status_scope = ["completed", "pending"];
      spendinganalysisRequest.frequency_unit = "monthly";
      spendinganalysisRequest.frequency = 1;
      spendinganalysisRequest.start_date = "2020-10-10";
      spendinganalysisRequest.end_date = "2021-01-10";
      spendinganalysisRequest.show_by_category = true;
      spendinganalysisRequest.show_by_period = true;
      spendinganalysisRequest.show_by_merchant = true;
      spendinganalysisRequest.only_cleansed = true;
      spendinganalysisRequest.only_active_clients = true;
      api.spendingAnalysis(spendinganalysisRequest, callback)

ARGUMENTS

Parameter Description
business_ids
array[UUID], conditional requirement
ID(s) of the Nucleus Business(es) used to source transaction data. All transactions linked to each business will be considered. Conditionally required if one of household_ids, client_ids, card_ids, or account_ids is not provided.
household_ids
array[UUID], conditional requirement
ID(s) of the Nucleus Household(s) used to source transaction data. All transactions linked to each household will be considered. Conditionally required if one of business_ids, client_ids, card_ids, or account_ids is not provided.
client_ids
array[UUID], conditional requirement
ID(s) of the Nucleus Client(s) used to source transaction data. All transactions linked to each client will be considered. Conditionally required if one of business_ids, household_ids, card_ids, or account_ids is not provided.
card_ids
array[UUID], conditional requirement
ID(s) of the Nucleus Card(s) used to source transaction data. All transactions linked to each card will be considered. Conditionally required if one of business_ids, household_ids, client_ids, or account_ids is not provided.
account_ids
array[UUID], conditional requirement
ID(s) of the Nucleus Account(s) used to source transaction data. All transactions linked to each account will be considered. Conditionally required if one of business_ids, household_ids, client_ids, or card_ids is not provided.
currency_code
string
The alphabetic currency code used to conduct the analysis, limited to 3 characters. Only records with this currency code will be considered. Defaults to USD if currency_conversion is not provided. If currency_conversion is provided, all origin currencies will be considered by default. See Currencies.
currency_conversion
string
The alphabetic currency code used to conduct the analysis, limited to 3 characters. Records will be converted from their original currency to the one indicated here. Conversions are supported both to and from the following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See Currencies.
card_status_scope
array[string]
If populated, only cards whose status matches one of the array values are considered in the analysis. Defaults to null, meaning transaction data from all cards are considered regardless of the status. Only applicable when scope is set to cards.
transaction_status_scope
array[string]
If populated, only transactions whose status matches one of the array values are considered in the analysis. Defaults to null, meaning all transactions are considered regardless of the status.
transaction_category_scope
array[UUID]
If populated, only transactions whose transaction_category_id matches one of the array values are considered in the analysis. A transaction_category_id is considered primary if it has a subcategory of null, meaning it represents a high-level category grouping. If a primary transaction_category_id is passed, then this scope will also include any transaction_category_ids with the same category value and different subcategory values. Defaults to null, meaning all transactions are considered regardless of the transaction_category_id. See Transaction Categories.
merchant_scope
array[UUID]
If populated, only transactions whose merchant_id matches one of the array values are considered in the analysis. Defaults to null, meaning all transactions are considered regardless of the merchant_id. See Merchants.
frequency_unit
string
Frequency unit of the analysis. Value may be daily, weekly, bi-weekly, monthly, quarterly, or annually. Defaults to monthly.
frequency
integer
Number of frequency_unit between each period. For example, if the frequency_unit is weekly and the frequency is 2, this means each period spans two weeks. Default is 1.
as_of_date
date
Reference date of the analysis that determines the starting point of the lookback_periods. Defaults to today’s date. Not applicable if a start_date and end_date are provided.
lookback_periods
integer
Number of lookback periods to analyze. Each period length is defined by the combination of frequency and frequency_unit provided, beginning at the as_of_date provided. For example, if frequency_unit is monthly, frequency is 1, and lookback_periods is 3, then the calendar month through the as_of_date, plus the previous 3 full calendar months, will be analyzed. Defaults to 0, meaning that only the period containing the as_of_date is analyzed. Not applicable if a start_date and end_date are provided.
start_date
date
Start date of the analysis. Conditionally required if end_date is passed. Passing start_date and end_date will override as_of_date and lookback_periods.
end_date
date
End date of the analysis. Conditionally required if start_date is passed. Passing start_date and end_date will override as_of_date and lookback_periods.
show_by_period
boolean
If true, a detailed history of spending will be returned over each of the periods determined by frequency_unit and frequency, over the entire analysis period determined by either as_of_date and lookback_periods or start_date and end_date. Defaults to false.
show_by_category
boolean
If true, return breakdowns of spending by category and subcategory. Defaults to false.
show_by_merchant
boolean
If true, return breakdowns of spending by merchant. Defaults to false.
only_cleansed
boolean
If true, only Portfolio Transactions with the is_cleansed parameter set to true will be considered. Defaults to false so that all transactions are considered.
only_active_clients
boolean
If true, only Clients with the is_active parameter set to true will be considered. Defaults to false so that all clients are considered.

Example Response

{
    "analysis_start": "2021-02-01",
    "analysis_end": "2021-04-26",
    "currency_code": "USD",
    "summary": {
        "number_of_transactions": 13,
        "amount_spent": 2267.7,
        "mean_transaction_amount": 174.44,
        "by_category": [
            {
                "category": "Automotive",
                "number_of_transactions": 13,
                "amount_spent": 2267.7,
                "mean_transaction_amount": 174.44,
                "weight": 1.0,
                "by_merchant": [
                    {
                        "merchant": "Pep Boys",
                        "merchant_id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740",
                        "number_of_transactions": 13,
                        "amount_spent": 2267.7,
                        "mean_transaction_amount": 174.44,
                        "weight": 1.0
                    }
                ],
                "subcategories": [
                    {
                        "subcategory": "Other",
                        "transaction_category_id": "e594f949-6f92-11eb-922d-124ab2ff7f93",
                        "number_of_transactions": 13,
                        "amount_spent": 2267.7,
                        "mean_transaction_amount": 174.44,
                        "weight": 1.0,
                        "by_merchant": [
                            {
                                "merchant": "Pep Boys",
                                "merchant_id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740",
                                "number_of_transactions": 13,
                                "amount_spent": 2267.7,
                                "mean_transaction_amount": 174.44,
                                "weight": 1.0
                            }
                        ]
                    }
                ]
            }
        ],
        "by_merchant": [
            {
                "merchant": "Pep Boys",
                "merchant_id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740",
                "number_of_transactions": 13,
                "amount_spent": 2267.7,
                "mean_transaction_amount": 174.44,
                "weight": 1.0,
                "by_category": [
                    {
                        "category": "Automotive",
                        "number_of_transactions": 13,
                        "amount_spent": 2267.7,
                        "mean_transaction_amount": 174.44,
                        "weight": 1.0,
                        "subcategories": [
                            {
                                "subcategory": "Other",
                                "transaction_category_id": "e594f949-6f92-11eb-922d-124ab2ff7f93",
                                "number_of_transactions": 13,
                                "amount_spent": 2267.7,
                                "mean_transaction_amount": 174.44,
                                "weight": 1.0
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "by_period": [
        {
            "period_start": "2021-02-01",
            "period_end": "2021-02-28",
            "analysis_start": "2021-02-01",
            "analysis_end": "2021-02-28",
            "number_of_transactions": 1,
            "amount_spent": 22.55,
            "mean_transaction_amount": 22.55,
            "by_category": [
                {
                    "category": "Automotive",
                    "number_of_transactions": 1,
                    "amount_spent": 22.55,
                    "mean_transaction_amount": 22.55,
                    "weight": 1.0,
                    "by_merchant": [
                        {
                            "merchant": "Pep Boys",
                            "merchant_id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740",
                            "number_of_transactions": 1,
                            "amount_spent": 22.55,
                            "mean_transaction_amount": 22.55,
                            "weight": 1.0
                        }
                    ],
                    "subcategories": [
                        {
                            "subcategory": "Other",
                            "transaction_category_id": "e594f949-6f92-11eb-922d-124ab2ff7f93",
                            "number_of_transactions": 1,
                            "amount_spent": 22.55,
                            "mean_transaction_amount": 22.55,
                            "weight": 1.0,
                            "by_merchant": [
                                {
                                    "merchant": "Pep Boys",
                                    "merchant_id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740",
                                    "number_of_transactions": 1,
                                    "amount_spent": 22.55,
                                    "mean_transaction_amount": 22.55,
                                    "weight": 1.0
                                }
                            ]
                        }
                    ]
                }
            ],
            "by_merchant": [
                {
                    "merchant": "Pep Boys",
                    "merchant_id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740",
                    "number_of_transactions": 1,
                    "amount_spent": 22.55,
                    "mean_transaction_amount": 22.55,
                    "weight": 1.0,
                    "by_category": [
                        {
                            "category": "Automotive",
                            "number_of_transactions": 1,
                            "amount_spent": 22.55,
                            "mean_transaction_amount": 22.55,
                            "weight": 1.0,
                            "subcategories": [
                                {
                                    "subcategory": "Other",
                                    "transaction_category_id": "e594f949-6f92-11eb-922d-124ab2ff7f93",
                                    "number_of_transactions": 1,
                                    "amount_spent": 22.55,
                                    "mean_transaction_amount": 22.55,
                                    "weight": 1.0
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "period_start": "2021-03-01",
            "period_end": "2021-03-31",
            "analysis_start": "2021-03-01",
            "analysis_end": "2021-03-31",
            "number_of_transactions": 12,
            "amount_spent": 2245.15,
            "mean_transaction_amount": 187.1,
            "by_category": [
                {
                    "category": "Automotive",
                    "number_of_transactions": 12,
                    "amount_spent": 2245.15,
                    "mean_transaction_amount": 187.1,
                    "weight": 1.0,
                    "by_merchant": [
                        {
                            "merchant": "Pep Boys",
                            "merchant_id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740",
                            "number_of_transactions": 12,
                            "amount_spent": 2245.15,
                            "mean_transaction_amount": 187.1,
                            "weight": 1.0
                        }
                    ],
                    "subcategories": [
                        {
                            "subcategory": "Other",
                            "transaction_category_id": "e594f949-6f92-11eb-922d-124ab2ff7f93",
                            "number_of_transactions": 12,
                            "amount_spent": 2245.15,
                            "mean_transaction_amount": 187.1,
                            "weight": 1.0,
                            "by_merchant": [
                                {
                                    "merchant": "Pep Boys",
                                    "merchant_id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740",
                                    "number_of_transactions": 12,
                                    "amount_spent": 2245.15,
                                    "mean_transaction_amount": 187.1,
                                    "weight": 1.0
                                }
                            ]
                        }
                    ]
                }
            ],
            "by_merchant": [
                {
                    "merchant": "Pep Boys",
                    "merchant_id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740",
                    "number_of_transactions": 12,
                    "amount_spent": 2245.15,
                    "mean_transaction_amount": 187.1,
                    "weight": 1.0,
                    "by_category": [
                        {
                            "category": "Automotive",
                            "number_of_transactions": 12,
                            "amount_spent": 2245.15,
                            "mean_transaction_amount": 187.1,
                            "weight": 1.0,
                            "subcategories": [
                                {
                                    "subcategory": "Other",
                                    "transaction_category_id": "e594f949-6f92-11eb-922d-124ab2ff7f93",
                                    "number_of_transactions": 12,
                                    "amount_spent": 2245.15,
                                    "mean_transaction_amount": 187.1,
                                    "weight": 1.0
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "period_start": "2021-04-01",
            "period_end": "2021-04-30",
            "analysis_start": "2021-04-01",
            "analysis_end": "2021-04-26",
            "number_of_transactions": 0,
            "amount_spent": 0,
            "mean_transaction_amount": 0,
            "by_category": [],
            "by_merchant": []
        }
    ]
}

RESPONSE

Field Description
analysis_start Start date of the analysis.
analysis_end End date of the analysis.
currency_code Currency code associated with monetary response values.
summary Summary of spending over the analysis period.
      number_of_transactions
      
Number of transactions over the analysis period.
      amount_spent
      
Amount spent over the analysis period.
      mean_transaction_amount
      
Average transaction amount over the analysis period.
      by_category
      
List of spending information separated by category and their relative subcategories. Only returned when show_by_category is set to true.
            category
      
Category as defined in the Nucleus transactions.
            number_of_transactions
      
Number of transactions over the analysis period for the given category.
            amount_spent
      
Amount spent over the analysis period for the given category.
            mean_transaction_amount
      
Average transaction amount over the analysis period for the given category.
            weight
      
Proportion of spending over the analysis period related to this category.
            by_merchant
      
List of spending information for the category, separated by merchant. Only returned when show_by_merchant is set to true.
                  merchant
      
Merchant as defined in the Nucleus transactions.
                  merchant_id
      
ID of the merchant record for the merchant. See Merchants.
                  number_of_transactions
      
Number of transactions over the analysis period for the given category and merchant.
                  amount_spent
      
Amount spent over the analysis period for the given category and merchant.
                  mean_transaction_amount
      
Average transaction amount over the analysis period for the given category and merchant.
                  weight
      
Proportion of spending over the analysis period related to this category and merchant.
            subcategories
      
List of subcategories for the given category.
                  subcategory
      
Subcategory as defined in the Nucleus transactions.
                  transaction_category_id
      
ID of the transaction category record for the given category/subcategory combination. See Transaction Categories.
                  number_of_transactions
      
Number of transactions over the analysis period for the given subcategory.
                  amount_spent
      
Amount spent over the analysis period for the given subcategory.
                  mean_transaction_amount
      
Average transaction amount over the analysis period for the given subcategory.
                  weight
      
Proportion of spending over the analysis period related to this subcategory.
                  by_merchant
      
List of spending information for the subcategory, separated by merchant. Only returned when show_by_merchant is set to true.
                        merchant
      
Merchant as defined in the Nucleus transactions.
                        merchant_id
      
ID of the merchant record for the merchant. See Merchants.
                        number_of_transactions
      
Number of transactions over the analysis period for the given subcategory and merchant.
                        amount_spent
      
Amount spent over the analysis period for the given subcategory and merchant.
                        mean_transaction_amount
      
Average transaction amount over the analysis period for the given subcategory and merchant.
                        weight
      
Proportion of spending over the analysis period related to this subcategory and merchant.
      by_merchant
      
List of spending information separated by merchant. Only returned when show_by_merchant is set to true.
            merchant
      
Merchant as defined in the Nucleus transactions.
            merchant_id
      
ID of the merchant record for the merchant. See Merchants.
            number_of_transactions
      
Number of transactions over the analysis period for the given merchant.
            amount_spent
      
Amount spent over the analysis period for the given merchant.
            mean_transaction_amount
      
Average transaction amount over the analysis period for the given merchant.
            weight
      
Proportion of spending over the analysis period related to this merchant.
            by_category
      
List of spending information for the merchant, separated by category and their relative subcategories. Only returned when show_by_category is set to true.
                  category
      
Category as defined in the Nucleus transactions.
                  number_of_transactions
      
Number of all transactions over the analysis period for the given merchant and category.
                  amount_spent
      
Amount spent over the analysis period for the given merchant and category.
                  mean_transaction_amount
      
Average transaction amount over the analysis period for the given merchant and category.
                  weight
      
Proportion of spending over the analysis period related to this merchant and category.
                  subcategories
      
List of subcategories for the given category.
                        subcategory
      
Subcategory as defined in the Nucleus transactions.
                        transaction_category_id
      
ID of the transaction category record for the given category/subcategory combination. See Transaction Categories
                        number_of_transactions
      
Number of transactions over the analysis period for the given merchant and subcategory.
                        amount_spent
      
Amount spent over the analysis period for the given merchant and subcategory.
                        mean_transaction_amount
      
Average transaction amount over the analysis period for the given merchant and subcategory.
                        weight
      
Proportion of spending over the analysis period related to this merchant and subcategory.
by_period Historical spending data, with frequency dependent on the values of frequency_unit and frequency passed in the request. Each entry has the fields shown below.
      period_start
      
Start date of the period.
      period_end
      
End date of the period.
      analysis_start
      
Start date of the analysis period.
      analysis_end
      
End date of the analysis period.
      number_of_transactions
      
Number of transactions over the period.
      amount_spent
      
Amount spent over the period.
      mean_transaction_amount
      
Average transaction amount over the period.
      by_category
      
List of spending information for the merchant, separated by category and their relative subcategories. Only returned when show_by_category is set to true.
            category
      
Category as defined in the Nucleus transactions.
            number_of_transactions
      
Number of transactions over the period for the given category.
            amount_spent
      
Amount spent over the period for the given category.
            mean_transaction_amount
      
Average transaction amount over the period for the given category.
            weight
      
Proportion of spending over the period related to this category.
            by_merchant
      
List of spending information for the category, separated by merchant. Only returned when show_by_merchant is set to true.
                  merchant
      
Merchant as defined in the Nucleus transactions.
                  merchant_id
      
ID of the merchant record for the merchant. See Merchants
                  number_of_transactions
      
Number of transactions over the period for the given category and merchant.
                  amount_spent
      
Amount spent over the period for the given category and merchant.
                  mean_transaction_amount
      
Average transaction amount over the period for the given category and merchant.
                  weight
      
Proportion of spending over the period related to this category and merchant.
            subcategories
      
List of subcategories for the given category.
                  subcategory
      
Subcategory as defined in the Nucleus transactions.
                  transaction_category_id
      
ID of the transaction category record for the given category/subcategory combination. See Transaction Categories.
                  number_of_transactions
      
Number of transactions over the period for the given subcategory.
                  amount_spent
      
Amount spent over the period for the given subcategory.
                  mean_transaction_amount
      
Average transaction amount over the period for the given category and merchant.
                  weight
      
Proportion of spending over the period related to this category and merchant.
                  by_merchant
      
List of spending information for the subcategory, separated by merchant. Only returned when show_by_merchant is set to true.
                        merchant
      
Merchant as defined in the Nucleus transactions.
                        merchant_id
      
ID of the merchant record for the merchant. See Merchants.
                        number_of_transactions
      
Number of transactions over the period for the given subcategory and merchant.
                        amount_spent
      
Amount spent over the period for the given subcategory and merchant.
                        mean_transaction_amount
      
Average transaction amount over the period for the given subcategory and merchant.
                        weight
      
Proportion of spending over the period related to this subcategory and merchant.
      by_merchant
      
List of spending information separated by merchant. Only returned when show_by_merchant is set to true.
            merchant
      
Merchant as defined in the Nucleus transactions.
            merchant_id
      
ID of the merchant record for the merchant. See Merchants.
            number_of_transactions
      
Number of transactions over the period for the given merchant.
            amount_spent
      
Amount spent over the period for the given merchant.
            mean_transaction_amount
      
Average transaction amount over the period for the given merchant.
            weight
      
Proportion of spending over the period related to this merchant.
            by_category
      
List of spending information for the merchant, separated by category and their relative subcategories. Only returned when show_by_category is set to true.
                  category
      
Category as defined in the Nucleus transactions.
                  number_of_transactions
      
Number of transactions over the period for the given merchant and category.
                  amount_spent
      
Amount spent over the period for the given merchant and category.
                  mean_transaction_amount
      
Average transaction amount over the period for the given merchant and category.
                  weight
      
Proportion of spending over the period related to this merchant and category.
                  subcategories
      
List of subcategories for the given merchant and category.
                        subcategory
      
Subcategory as defined in the Nucleus transactions.
                        transaction_category_id
      
ID of the transaction category record for the given category/subcategory combination. See Transaction Categories.
                        number_of_transactions
      
Number of transactions over the period for the given merchant and subcategory.
                        amount_spent
      
Amount spent over the period for the given merchant and subcategory.
                        mean_transaction_amount
      
Average transaction amount over the period for the given merchant and subcategory.
                        weight
      
Proportion of spending over the period related to this merchant and subcategory.

NUCLEUS DATA DEPENDENCIES

Goals

Accumulation Goal Allocation

This service offers a framework to match an accumulation goal to an appropriate portfolio, with the ability to prioritize an investor’s risk appetite or prioritize the goal achievement. Allocations are selected from a universe based upon best fit for the selected priority, drawing from pre-defined portfolios and dynamically generated portfolios. This framework also has built-in support for a goal recommendation engine, which recommends actions that may be taken to increase the expected goal achievement probability if a goal cannot be achieved in the initially presented allocation context.

HTTP REQUEST

Example Request

POST /goal_accumulation/allocation

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "allocation_method": "create",
        "allocation_priority": "goal",
        "allocations": [
            "406ec16e-ebae-4130-a6c0-1cacb72569a2",
            "740f6466-3300-4122-927d-4a691359fa32",
            "0a02058f-4046-48de-b3d2-aeefd6d4efac"
        ],
        "opt_config": {
            "tickers": ["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
            "min_assets": 6,
            "w_config": {
                "w_min_major": 0.05,
                "w_max_major": 1,
                "w_min_minor": 0.05,
                "w_max_minor": 0.1,
                "cash_amount": 0.0
            },
            "w_asset_config": {
                "US_Equities": 1.0,
                "Fixed_Income": 1.0,
                "Intl_Equities": 1.0,
                "EM_Equities": 1.0,
                "Commodities": 1.0
            },
            "sec_types": ["minor", "major", "minor", "minor", "minor", "minor"],
            "start_date": "2016-01-01",
            "end_date": "2017-01-01"
        },
        "risk_score": 77,
        "trading_days_per_year": 252,
        "horizon": 5,
        "horizon_frequency": "year",
        "deposit_config": [
            {
                "dep_start_reference": "a_start",
                "dep_start_period": 0,
                "dep_end_reference": "a_start",
                "dep_end_period": 3,
                "dep_amount": 2000,
                "dep_frequency": "year",
                "dep_inflation": 0.0
            }
        ],
        "goal_config": {
            "goal_amount": 25000,
            "goal_inflation": 0.0
        },
        "recommendation_config": {
            "recommend": true,
            "inv_min": 0,
            "inv_max": 1000,
            "dep_min": 0,
            "dep_max": 1000,
            "horizon_min": 1,
            "horizon_max": 10,
            "recommended_inflation": 0.0
        },
        "curr_inv": 10000,
        "recommend_type": "recurring",
        "conf_tgt": 0.9,
        "n": 1000,
        "remove_outliers": true,
        "thresh_type": "perc",
        "thresh": 0,
        "withdrawal_tax": 0.0,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0,
        "use_proxy_data": false
    }' "https://api.hydrogenplatform.com/proton/v1/goal_accumulation/allocation"
GoalsApi goalsApi = new GoalsApi();
        GoalConfig goalConfig = new GoalConfig();
        goalConfig.setGoalAmount(BigDecimal.valueOf(25000L));
        goalConfig.setGoalInflation(0F);
        AccumulationGoalDepositConfig goalDepositConfig = new AccumulationGoalDepositConfig();
        goalDepositConfig.setDepAmount(BigDecimal.valueOf(2000));
        goalDepositConfig.setDepStartReference(AccumulationGoalDepositConfig.DepStartReferenceEnum.START);
        goalDepositConfig.setDepStartPeriod(0);
        goalDepositConfig.setDepEndReference(AccumulationGoalDepositConfig.DepEndReferenceEnum.START);
        goalDepositConfig.setDepEndPeriod(3);
        goalDepositConfig.setDepInflation(0F);


        RecommendationConfig recommendationConfig = new RecommendationConfig();
        recommendationConfig.setRecommend(true);
        recommendationConfig.setInvMin(BigDecimal.ZERO);
        recommendationConfig.setInvMax(BigDecimal.valueOf(1000L));
        recommendationConfig.setDepMin(BigDecimal.ZERO);
        recommendationConfig.setDepMax(BigDecimal.valueOf(1000L));
        recommendationConfig.setHorizonMin(1);
        recommendationConfig.setHorizonMax(10);
        recommendationConfig.setRecommendedInflation(0F);

        RecommendationConfig1 recommendationConfig1 = new RecommendationConfig1();
        recommendationConfig1.setInvMin(BigDecimal.ZERO);
        recommendationConfig1.setInvMax(BigDecimal.valueOf(1000L));
        recommendationConfig1.setDepMin(BigDecimal.ZERO);
        recommendationConfig1.setDepMax(BigDecimal.valueOf(1000L));
        recommendationConfig1.setHorizonMin(1);
        recommendationConfig1.setHorizonMax(10);
        recommendationConfig1.setRecommendedInflation(0F);
GoalAccumulationAllocationRequest goalAccumulationAllocationRequest = new GoalAccumulationAllocationRequest();
        goalAccumulationAllocationRequest.setAllocationMethod(GoalAccumulationAllocationRequest.AllocationMethodEnum.CREATE);
        goalAccumulationAllocationRequest.setAllocationPriority(GoalAccumulationAllocationRequest.AllocationPriorityEnum.GOAL);
        OptConfig optConfig = new OptConfig();
        optConfig.setTickers(Arrays.asList( "CVX",
                "PFE",
                "JNJ"));
        optConfig.setMinAssets(3);
        WConfig wConfig = new WConfig();
        wConfig.setWMinMajor(0.05F);
        wConfig.setWMaxMajor(1F);
        wConfig.setWMinMinor(0.05F);
        wConfig.setWMaxMinor(1F);
        wConfig.setCashAmount(0F);
        optConfig.setWConfig(wConfig);
        Map<String, Object> wAssetConfig = new HashMap<>();
        wAssetConfig.put("US_Equities", 1);
        wAssetConfig.put("Fixed_Income", 1);
        wAssetConfig.put("Intl_Equities", 1);
        optConfig.setWAssetConfig(wAssetConfig);
        optConfig.setSecTypes(Arrays.asList(
                OptConfig.SecTypesEnum.MINOR, OptConfig.SecTypesEnum.MAJOR, OptConfig.SecTypesEnum.MINOR
        ));
        optConfig.setStartDate(LocalDate.parse("2017-01-01"));
        optConfig.setEndDate(LocalDate.parse("2018-12-31"));
        goalAccumulationAllocationRequest.setOptConfig(optConfig);
        goalAccumulationAllocationRequest.setCurrInv(BigDecimal.valueOf(10000L));
        goalAccumulationAllocationRequest.setHorizon(5);
        goalAccumulationAllocationRequest.setHorizonFrequency(GoalAccumulationAllocationRequest.HorizonFrequencyEnum.YEAR);
        goalAccumulationAllocationRequest.setGoalConfig(goalConfig);
        goalAccumulationAllocationRequest.setDepositConfig(Arrays.asList(
                goalDepositConfig
        ));
        goalAccumulationAllocationRequest.setRecommendationConfig(recommendationConfig);
        goalAccumulationAllocationRequest.setRecommendType(GoalAccumulationAllocationRequest.RecommendTypeEnum.RECURRING);
        goalAccumulationAllocationRequest.setConfTgt(0.9F);
        goalAccumulationAllocationRequest.setN(1000);
        goalAccumulationAllocationRequest.setRemoveOutliers(Boolean.TRUE);
        goalAccumulationAllocationRequest.setThreshType(GoalAccumulationAllocationRequest.ThreshTypeEnum.PERC);
        goalAccumulationAllocationRequest.setThresh(BigDecimal.ZERO);
        goalAccumulationAllocationRequest.setWithdrawalTax(0F);
        goalAccumulationAllocationRequest.setTradingDaysPerYear(252);
        goalAccumulationAllocationRequest.setRiskScore(BigDecimal.valueOf(77L));
        goalAccumulationAllocationRequest.setAdjustForCompounding(Boolean.FALSE);
        goalAccumulationAllocationRequest.setCompoundingRate(0F);
        goalAccumulationAllocationRequest.setUseProxyData(Boolean.FALSE);
        goalAccumulationAllocationRequest.setMarketDataSource(GoalAccumulationAllocationRequest.MarketDataSourceEnum.NUCLEUS);
        goalAccumulationAllocationRequest.setCreateLog(Boolean.FALSE);
        Map<String, Object> goalAccumulationAllocationResponse =
                goalsApi.goalAccumulationAllocation(goalAccumulationAllocationRequest);
        System.out.println(goalAccumulationAllocationResponse);
api_instance = proton_api.GoalsApi(proton_api.ApiClient(configuration))
goal_config = proton_api.GoalConfig(goal_amount=25000, goal_inflation=0)
accumulation_goal_deposit_config = proton_api.AccumulationGoalDepositConfig(
    dep_amount=2000, dep_start_reference='a_start', dep_start_period=0, dep_end_reference='a_start',
    dep_end_period=3, dep_inflation=0
)
recommendation_config = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

recommendation_config1 = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

goal_accumulation_allocation_request = proton_api.GoalAccumulationAllocationRequest(
    allocation_method='create', allocation_priority='goal', opt_config=proton_api.OptConfig(
        tickers=["CVX",
                 "PFE",
                 "JNJ"], min_assets=3, w_config=proton_api.WConfig(
            w_min_major=0.05, w_max_major=1, w_min_minor=0.05, w_max_minor=1, cash_amount=0
        ), w_asset_config={
            "US_Equities": 1,
            "Fixed_Income": 1,
            "Intl_Equities": 1
        }, sec_types=['minor', 'major', 'major'],
        start_date="2017-01-01", end_date="2018-12-31"
    ), curr_inv=10000, horizon=5, horizon_frequency='year', goal_config=goal_config,
    deposit_config=[accumulation_goal_deposit_config], recommendation_config=recommendation_config,
    recommend_type='recurring', conf_tgt=0.9, n=1000, remove_outliers=True, thresh_type='perc',
    thresh=0, withdrawal_tax=0, trading_days_per_year=252, risk_score=77, adjust_for_compounding=False,
    compounding_rate=0, use_proxy_data=False, market_data_source='nucleus', create_log=False
)
try:
    # GoalApi - Goal Accumulation Allocation
    api_response = api_instance.goal_accumulation_allocation(goal_accumulation_allocation_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling GoalApi->goal_accumulation_allocation: %s\n" % e)
api_instance = ProtonApi::GoalsApi.new
goalAccumulationAllocationRequest = ProtonApi::GoalAccumulationAllocationRequest.new
# AccumulationGoalDepositConfig
accumulationDepositConfig = ProtonApi::AccumulationGoalDepositConfig.new
accumulationDepositConfig.dep_amount = 2000
accumulationDepositConfig.dep_start_reference = "a_start"
accumulationDepositConfig.dep_start_period = 0
accumulationDepositConfig.dep_end_reference = "a_start"
accumulationDepositConfig.dep_end_period = 3
accumulationDepositConfig.dep_frequency = "year"
accumulationDepositConfig.dep_inflation = 0
# Recommendation Config
recommendationConfig = ProtonApi::RecommendationConfig.new
recommendationConfig.recommend = true
recommendationConfig.inv_max = 1000
recommendationConfig.inv_min = 0
recommendationConfig.dep_min = 0
recommendationConfig.dep_max = 1000
recommendationConfig.horizon_min = 1
recommendationConfig.horizon_max = 10
recommendationConfig.recommended_inflation = 0
# Goal Config
goalConfig = ProtonApi::GoalConfig.new
goalConfig.goal_amount = 25000
goalConfig.goal_inflation = 0
# wConfig
wConfig = ProtonApi::WConfig1.new
wConfig.w_max_major = 1
wConfig.w_max_minor = 1
wConfig.w_min_major = 0
wConfig.w_min_minor = 0
wConfig.cash_amount = 0
# w_asset_config
w_asset_config = {
    "US_Equities" => 1,
    "Fixed_Income" => 1,
    "Intl_Equities" => 1
}
begin
  goalAccumulationAllocationRequest.allocation_method = "create"
  goalAccumulationAllocationRequest.allocation_priority = "goal"
  optConfig = ProtonApi::OptConfig.new
  optConfig.w_asset_config = w_asset_config
  optConfig.min_assets = 3
  optConfig.sec_types = ["minor", "major", "minor"]
  optConfig.w_config = wConfig
  optConfig.start_date = "2017-01-01"
  optConfig.end_date = "2018-12-31"
  optConfig.tickers = ["CVX", "PFE", "JNJ"]
  goalAccumulationAllocationRequest.opt_config = optConfig
  goalAccumulationAllocationRequest.curr_inv = 10000
  goalAccumulationAllocationRequest.horizon = 5
  goalAccumulationAllocationRequest.horizon_frequency = "year"

  goalAccumulationAllocationRequest.goal_config = goalConfig
  goalAccumulationAllocationRequest.deposit_config =
      [
          accumulationDepositConfig
      ]
  goalAccumulationAllocationRequest.recommendation_config = recommendationConfig
  goalAccumulationAllocationRequest.recommend_type = "recurring"
  goalAccumulationAllocationRequest.conf_tgt = 0.9
  goalAccumulationAllocationRequest.n = 1000
  goalAccumulationAllocationRequest.remove_outliers = true
  goalAccumulationAllocationRequest.thresh_type = "perc"
  goalAccumulationAllocationRequest.thresh = 0
  goalAccumulationAllocationRequest.withdrawal_tax = 0
  goalAccumulationAllocationRequest.trading_days_per_year = 252
  goalAccumulationAllocationRequest.risk_score = 77
  goalAccumulationAllocationRequest.adjust_for_compounding = false
  goalAccumulationAllocationRequest.compounding_rate = 0
  goalAccumulationAllocationRequest.use_proxy_data = false
  goalAccumulationAllocationRequest.market_data_source = "nucleus"
  goalAccumulationAllocationRequest.create_log = false
  goalAccumulationAllocationResponse = api_instance.goal_accumulation_allocation(goalAccumulationAllocationRequest)
  p goalAccumulationAllocationResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling goal_accumulation_allocation_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\GoalsApi(
    new GuzzleHttp\Client(),
    $config
);
$goalAccumulationAllocationRequest = new com\hydrogen\proton\Model\GoalAccumulationAllocationRequest();
try {
    $goalAccumulationAllocationRequest->setallocationmethod("create");
    $goalAccumulationAllocationRequest->setallocationpriority("goal");
    $optConfig=new \com\hydrogen\proton\Model\OptConfig();
    $optConfig->setTickers(array("CVX","PFE","JNJ"));
    $optConfig->setMinAssets(3);
    $wConfig = new \com\hydrogen\proton\Model\WConfig();
    $wConfig->setWMinMajor(0.05);
    $wConfig->setWMaxMajor(1);
    $wConfig->setWMinMinor(0.05);
    $wConfig->setWMaxMinor(1);
    $wConfig->setCashAmount(0);
    $optConfig->setWConfig($wConfig);
    $wAssetConfig = new stdClass();
    $wAssetConfig->US_Equities = 1;
    $wAssetConfig->Fixed_Income =1;
    $wAssetConfig->Intl_Equities=1;
    $optConfig->setWAssetConfig($wAssetConfig);
    $optConfig->setSecTypes(array("major","minor","minor"));
    $optConfig->setStartDate("2017-01-01");
    $optConfig->setEndDate("2018-12-31");

    $goalAccumulationAllocationRequest->setOptConfig($optConfig);
    $goalAccumulationAllocationRequest->setcurrinv(10000);
    $goalAccumulationAllocationRequest->setHorizon(5);
    $goalAccumulationAllocationRequest->sethorizonfrequency("year");
    $goalConfig = new \com\hydrogen\proton\Model\GoalConfig();
    $goalConfig->setGoalAmount(25000);
    $goalConfig->setGoalInflation(0);
    $goalAccumulationAllocationRequest->setGoalConfig($goalConfig);

    $depositConfig = new \com\hydrogen\proton\Model\AccumulationGoalDepositConfig();
    $depositConfig->setDepStartReference("a_start");
    $depositConfig->setDepStartPeriod(0) ;
    $depositConfig->setDepEndReference("a_start");
    $depositConfig->setDepEndPeriod(3);
    $depositConfig->setDepAmount(2000) ;
    $depositConfig->setDepInflation(0);
    $goalAccumulationAllocationRequest->setDepositConfig(array($depositConfig));

    $recommendationConfig= new \com\hydrogen\proton\Model\RecommendationConfig();
    $recommendationConfig->setRecommend(true);
    $recommendationConfig->setInvMin(0);
    $recommendationConfig->setInvMax(1000);
    $recommendationConfig->setDepMax(1000);
    $recommendationConfig->setDepMin(0);
    $recommendationConfig->setHorizonMin(1);
    $recommendationConfig->setHorizonMax(10);
    $recommendationConfig->setRecommendedInflation(0);
    $goalAccumulationAllocationRequest->setRecommendationConfig($recommendationConfig);
    $goalAccumulationAllocationRequest->setRecommendType("recurring");
    $goalAccumulationAllocationRequest->setConfTgt(0.9);
    $goalAccumulationAllocationRequest->setN(1000);
    $goalAccumulationAllocationRequest->setRemoveOutliers(true);
    $goalAccumulationAllocationRequest->setThreshType('perc');
    $goalAccumulationAllocationRequest->setThresh(0);
    $goalAccumulationAllocationRequest->setWithdrawalTax(0);
    $goalAccumulationAllocationRequest->setTradingDaysPerYear(252);
    $goalAccumulationAllocationRequest->setRiskScore(77);
    $goalAccumulationAllocationRequest->setAdjustForCompounding(false);
    $goalAccumulationAllocationRequest->setCompoundingRate(0);
    $goalAccumulationAllocationRequest->setUseProxyData(false);
    $goalAccumulationAllocationRequest->setMarketDataSource("nucleus");
    $goalAccumulationAllocationRequest->setCreateLog(false);
    $result = $apiInstance->goalAccumulationAllocation($goalAccumulationAllocationRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling GoalsApi->goalAccumulationAllocation: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.GoalsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.GoalsApi();
    var goalaccumulationallocationRequest= new HydrogenProtonApi.GoalAccumulationAllocationRequest();
    goalaccumulationallocationRequest.allocation_method= "create";
    goalaccumulationallocationRequest.allocation_priority="goal";
    goalaccumulationallocationRequest.opt_config= {
        "tickers": [
            "CVX",
            "PFE",
            "JNJ"
        ],
        "min_assets": 3,
        "w_config": {
            "w_min_major": 0.05,
            "w_max_major": 1,
            "w_min_minor": 0.05,
            "w_max_minor": 1,
            "cash_amount": 0
        },
        "w_asset_config": {
            "US_Equities": 1,
            "Fixed_Income": 1,
            "Intl_Equities": 1
        },
        "sec_types": [
            "minor",
            "major",
            "minor"
        ],
        "start_date": "2017-01-01",
        "end_date": "2018-12-31"
    },
        goalaccumulationallocationRequest.curr_inv= 10000;
    goalaccumulationallocationRequest.horizon= 5;
    goalaccumulationallocationRequest.horizon_frequency= "year";
    goalaccumulationallocationRequest.goal_config= {
        "goal_amount": 25000,
        "goal_inflation": 0
    };
    goalaccumulationallocationRequest.deposit_config= [
        {
            "dep_start_reference": "a_start",
            "dep_start_period": 0,
            "dep_end_reference": "a_start",
            "dep_end_period": 3,
            "dep_amount": 2000,
            "dep_inflation": 0
        }
    ];
    goalaccumulationallocationRequest.recommendation_config= {
        "recommend": true,
        "inv_min": 0,
        "inv_max": 1000,
        "dep_min": 0,
        "dep_max": 1000,
        "horizon_min": 1,
        "horizon_max": 10,
        "recommended_inflation": 0
    };
    goalaccumulationallocationRequest.recommend_type="recurring";
    goalaccumulationallocationRequest.conf_tgt= 0.9;
    goalaccumulationallocationRequest.n= 1000;
    goalaccumulationallocationRequest.remove_outliers= "true";
    goalaccumulationallocationRequest.thresh_type="perc";
    goalaccumulationallocationRequest.thresh= 0;
    goalaccumulationallocationRequest.withdrawal_tax= 0;
    goalaccumulationallocationRequest.trading_days_per_year= 252;
    goalaccumulationallocationRequest.risk_score= 77;
    goalaccumulationallocationRequest.adjust_for_compounding="false";
    goalaccumulationallocationRequest.compounding_rate=0;
    goalaccumulationallocationRequest.use_proxy_data= "false";
    goalaccumulationallocationRequest.create_log= "false";
    goalaccumulationallocationRequest.market_data_source= "nucleus";
    api.goalAccumulationAllocation(goalaccumulationallocationRequest, callback)

ARGUMENTS

Parameter Description
allocation_method
string, required
The allocation universe source, may be either create or select. create constructs an allocation universe from a dynamically generated efficient frontier, based on opt_config. select derives an allocation universe from pre-defined allocations, as stipulated by allocations.
allocation_priority
string, required
The priority to consider when deriving the appropriate allocation, may be risk or goal. risk finds a portfolio that corresponds to an investor’s risk_score within the universe of potential portfolios. goal does not consider the investor’s risk_score, but rather allocates to a portfolio that best achieves the goal.
opt_config
map, conditional requirement
Portfolio optimization configuration, required if allocation_method = create. Information in opt_config refers to security data, which must be created in advance using the Nucleus endpoints POST /security and POST /security_price. opt_config includes the fields shown below.
      tickers
      array, required
A list of tickers to consider during the optimization process, referencing securities defined in the Nucleus API. We recommend using no more than 25 tickers in a single optimization. Pre-screening a securities universe prior to calling the service will result in faster execution times as well as more meaningful results.
      min_assets
      integer, required
The minimum number of portfolio assets, excluding the cash security (if applicable).
      w_config
      map, required
Weight constraints for security types, including w_min_major, w_max_major, w_min_minor, w_max_minor, and cash_amount, which stipulate lower and upper bounds for minor and major securities, as well as a constant weight for cash securities. Minimums are joined with zero to form a binary constraint. This means that the minimum weight of securities of each type may either be 0 or the stipulated minimum. For example, a w_min_major constraint of 5% indicates that if a major security is chosen during the optimization, its weight will be either 0% or >= 5%.
      w_asset_config
      map
Weight constraints for asset classes. Stipulates a maximum weight for the asset classes represented in tickers. If an asset class is represented in tickers but not found in w_asset_config, the weight for that asset class will not be constrained.
      sec_types
      array, required
A type for each security in tickers. Values may be major, minor, and cash. major securities are intended to be securities with more lenient weight thresholds. minor securities are intended to be securities with tighter weight thresholds. cash securities are constrained to a constant weight. major and minor designations interact with w_config to set distinct weight constraints for different kinds of securities. A maximum of one security may be labelled with the cash type.
      start_date
      date
Start date for historical prices in yyyy-mm-dd format.
      end_date
      date
End date for historical prices in yyyy-mm-dd format.
allocations
array(UUID)
List of allocation_ids in the Nucleus API to select from. As a pre-requisite, must have values for the performance and volatility arguments within the chosen allocation_id. Defaults to include all available allocations.
curr_inv
float, conditional requirement
The current amount invested toward the goal.
horizon
integer, conditional requirement
The goal horizon, with a frequency defined by horizon_frequency. For example, for a client that is looking to make a major purchase in 30 years, use horizon = 30.
horizon_frequency
string, conditional requirement
The frequency in relation to the number defined in horizon, and at which to run the simulation. Must be one of the following: year, quarter, month, week, day.
goal_config
map, required
Information to configure the accumulation goal amount.
      goal_amount
      string, conditional requirement
The target goal amount, in today’s dollars.
      goal_inflation
      integer
The annualized inflation rate for goal_amount. Defaults to 0.
deposit_config
array(map)
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below.
      dep_start_reference
      string
The reference for the starting point of the deposit. May be a_start or a_end, which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_start.
      dep_start_period
      integer
The starting period for the deposit, relative to dep_start_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_end_reference
      string
The reference for the ending point of the deposit. May be a_start or a_end, which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_end.
      dep_end_period
      integer
The ending period for the deposit, relative to dep_end_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_amount
      float
The deposit amount, in today’s dollars. Defaults to 0.
      dep_frequency
      string
The frequency of the deposit. Must be one of the following: year, quarter, month, week, day. Defaults to year.
      dep_inflation
      float
The annualized inflation rate for the deposit. Defaults to 0.
recommendation_config
map
Information to configure the goal recommendation engine, including the fields shown below.
      recommend
      boolean
If true, generate a recommended action to improve goal probability. Recommendations are only generated if a goal is off-track. Defaults to true.
      inv_min
      float
The lower bound for one-time deposit recommendations. Defaults to 0.
      inv_max
      float
The upper bound for one-time deposit recommendations. Defaults to goal_amount.
      dep_min
      float
The lower bound for recurring deposit recommendations. Defaults to 0.
      dep_max
      float
The upper bound for recurring deposit recommendations. Defaults to goal_amount divided by horizon.
      horizon_min
      integer
The minimum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 1.
      horizon_max
      integer
The maximum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 64.
      recommended_inflation
      float
The annualized inflation rate attributed to a recommended recurring deposit.
recommend_type
string
The type of recommended action. Value may be recurring, one-time, combo, or horizon. recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon.
conf_tgt
float
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90.
n
integer
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000.
remove_outliers
boolean
If true, remove outlying results. If true, outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true.
thresh_type
string
The goal deviation threshold type. Value may be perc or amnt. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc.
thresh
float
The goal deviation threshold value, corresponding to thresh_type. Defaults to 0.
withdrawal_tax
float
The tax rate to apply to all withdrawals. Defaults to 0.
trading_days_per_year
integer
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day. Defaults to 252.
risk_score
integer
The investor’s risk score from 0 to 100, where 0 indicates minimum risk appetite and 100 indicates maximum risk appetite.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.
market_data_source
string
Source of security price data to be used in the analysis. Value may be nucleus or integration. When value is nucleus, security price data is sourced from Nucleus Security Price. When value is integration, security price data is sourced from a configured Integration Market Data vendor. Defaults to nucleus.
client_id
UUID, conditional requirement
The ID of a Nucleus client used to derive one or more of the following: curr_inv, horizon, horizon_frequency, and goal_config.goal_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
goal_id
UUID, conditional requirement
The ID of a Nucleus goal used to derive one or more of the following:curr_inv, horizon, horizon_frequency, and goal_config.goal_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
create_log
boolean
If true, a record of this Proton request URL, request body, response body, and Nucleus UUID(s), where applicable, will be stored in Electron as an audit log, and the resulting audit_log_id will be returned in the Proton response. Defaults to false.

Example Response

{
    "current_status": {
        "on_track": false,
        "progress": 0.4,
        "goal_probability": 0.5937,
        "goal_achievement_score": 66,
        "return_details": {
            "0": {
                "period_earnings": 0,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 0,
                "cumulative_deposits": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 10000
            },
            "1": {
                "period_earnings": 353.71,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 353.71,
                "cumulative_deposits": 2000,
                "cumulative_withdrawals": 0,
                "ending_balance": 12353.71
            },
            "2": {
                "period_earnings": 853.48,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 1207.19,
                "cumulative_deposits": 4000,
                "cumulative_withdrawals": 0,
                "ending_balance": 15207.19
            },
            "3": {
                "period_earnings": 1417.59,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 2624.78,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 18624.78
            },
            "4": {
                "period_earnings": 1569.72,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 4194.5,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 20194.5
            },
            "5": {
                "period_earnings": 1914.63,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 6109.14,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 22109.14
            }
        },
        "adjusted_goal_amount": 25000,
        "final_balance": 22109.14
    },
    "recommended_status": {
        "on_track": true,
        "progress": 0.4,
        "goal_probability": 0.9019,
        "goal_achievement_score": 100,
        "action": [
            {
                "value": 500,
                "freq_unit": "year",
                "value_type": "recurring_deposit"
            }
        ],
        "return_details": {
            "0": {
                "period_earnings": 0,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 0,
                "cumulative_deposits": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 10000
            },
            "1": {
                "period_earnings": 382.47,
                "period_deposit": 2500,
                "period_withdrawal": 0,
                "cumulative_earnings": 382.47,
                "cumulative_deposits": 2500,
                "cumulative_withdrawals": 0,
                "ending_balance": 12882.47
            },
            "2": {
                "period_earnings": 957.58,
                "period_deposit": 2500,
                "period_withdrawal": 0,
                "cumulative_earnings": 1340.05,
                "cumulative_deposits": 5000,
                "cumulative_withdrawals": 0,
                "ending_balance": 16340.05
            },
            "3": {
                "period_earnings": 1404.76,
                "period_deposit": 2500,
                "period_withdrawal": 0,
                "cumulative_earnings": 2744.81,
                "cumulative_deposits": 7500,
                "cumulative_withdrawals": 0,
                "ending_balance": 20244.81
            },
            "4": {
                "period_earnings": 1802.08,
                "period_deposit": 500,
                "period_withdrawal": 0,
                "cumulative_earnings": 4546.89,
                "cumulative_deposits": 8000,
                "cumulative_withdrawals": 0,
                "ending_balance": 22546.89
            },
            "5": {
                "period_earnings": 1993.62,
                "period_deposit": 500,
                "period_withdrawal": 0,
                "cumulative_earnings": 6540.5,
                "cumulative_deposits": 8500,
                "cumulative_withdrawals": 0,
                "ending_balance": 25040.5
            }
        },
        "adjusted_goal_amount": 25000,
        "final_balance": 25040.5
    },
    "allocation": {
        "ret": 0.1177,
        "risk": 0.0665,
        "assets": [
            "AGG",
            "AMZN",
            "CMCSA",
            "GOOGL",
            "KHC",
            "XOM"
        ],
        "weights": [
            0.5,
            0.1,
            0.1,
            0.1,
            0.1,
            0.1
        ],
        "identifier": null
    }
}

RESPONSE

Field Description
current_status The current status of the goal.
      on_track If true, the goal is on track.
      progress The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon.
      goal_probability The probability of achieving the goal with the given portfolio.
      goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
      return_details Portfolio return information over the length of the horizon, broken down by period.
            period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
            period_deposit The deposit made for this period in the accumulation phase.
            period_withdrawal The withdrawal made for this period.
            cumulative_earnings The cumulative investment earnings made up to and including this period.
            cumulative_deposits The cumulative deposits made up to and including this period for the decumulation phase.
            cumulative_withdrawals The cumulative withdrawals made up to and including this period.
            ending_balance The ending balance, inclusive of earnings and contributions for the current period.
      adjusted_goal_amount The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold.
      final_balance The projected final balance from return_details.
recommended_status The goal status based on the provided recommendation.
      on_track If true, the goal is on track.
      progress The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon.
      goal_probability The probability of achieving the goal with the given portfolio.
      goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
      action The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits.
            value The value of the recommended action.
            freq_unit The frequency unit of value.
            value_type The type of recommendation being made.
      return_details Portfolio return information over the length of the horizon, broken down by period.
            period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
            period_deposit The deposit made for this period in the accumulation phase.
            period_withdrawal The withdrawal made for this period.
            cumulative_earnings The cumulative investment earnings made up to and including this period.
            cumulative_deposits The cumulative deposits made up to and including this period for the decumulation phase.
            cumulative_withdrawals The cumulative withdrawals made up to and including this period.
            ending_balance The ending balance, inclusive of earnings and contributions for the current period.
      adjusted_goal_amount The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold.
      final_balance The projected final balance from return_details.
allocation Information about the chosen portfolio, including risk and return.
      ret The portfolio annualized return.
      risk The portfolio annualized standard deviation.
      assets The securities in the created portfolio, returned if allocation_method = create.
      weights The weights for each of the securities in the created portfolio, returned if allocation_method = create.
      identifier The allocation’s id, returned if allocation_method = select.
audit_log_id The unique id of the audit log record created in Electron. Only returned when create_log = true.

NUCLEUS DATA DEPENDENCIES

Accumulation Goal Recommendation

This service is a recommendation engine that generates actions to increase the likelihood of achieving an accumulation goal, based on portfolio attributes and a target goal amount. Available actions include various types of cash inflows as well as goal horizon extension. The engine will attempt to find the minimal recommended action that satisfies a goal confidence target, subject to the given constraints.

HTTP REQUEST

POST /goal_accumulation/recommendation

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "p_ret": [0.09],
        "p_risk": [0.05],
        "trading_days_per_year": 252,
        "horizon": 5,
        "horizon_frequency": "year",
        "deposit_config": [
            {
                "dep_start_reference": "a_start",
                "dep_start_period": 0,
                "dep_end_reference": "a_start",
                "dep_end_period": 3,
                "dep_amount": 2000,
                "dep_frequency": "year",
                "dep_inflation": 0.0
            }
        ],
        "goal_config": {
            "goal_amount": 25000,
            "goal_inflation": 0.0
        },
        "recommendation_config": {
            "inv_min": 0,
            "inv_max": 1000,
            "dep_min": 0,
            "dep_max": 1000,
            "horizon_min": 1,
            "horizon_max": 10,
            "recommended_inflation": 0.0
        },
        "curr_inv": 10000,
        "recommend_type": "recurring",
        "conf_tgt": 0.9,
        "n": 1000,
        "remove_outliers": true,
        "thresh_type": "perc",
        "thresh": 0,
        "withdrawal_tax": 0.0,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0
    }' "https://api.hydrogenplatform.com/proton/v1/goal_accumulation/recommendation"
GoalsApi goalsApi = new GoalsApi();
        GoalConfig goalConfig = new GoalConfig();
        goalConfig.setGoalAmount(BigDecimal.valueOf(25000L));
        goalConfig.setGoalInflation(0F);
        AccumulationGoalDepositConfig goalDepositConfig = new AccumulationGoalDepositConfig();
        goalDepositConfig.setDepAmount(BigDecimal.valueOf(2000));
        goalDepositConfig.setDepStartReference(AccumulationGoalDepositConfig.DepStartReferenceEnum.START);
        goalDepositConfig.setDepStartPeriod(0);
        goalDepositConfig.setDepEndReference(AccumulationGoalDepositConfig.DepEndReferenceEnum.START);
        goalDepositConfig.setDepEndPeriod(3);
        goalDepositConfig.setDepInflation(0F);


        RecommendationConfig recommendationConfig = new RecommendationConfig();
        recommendationConfig.setRecommend(true);
        recommendationConfig.setInvMin(BigDecimal.ZERO);
        recommendationConfig.setInvMax(BigDecimal.valueOf(1000L));
        recommendationConfig.setDepMin(BigDecimal.ZERO);
        recommendationConfig.setDepMax(BigDecimal.valueOf(1000L));
        recommendationConfig.setHorizonMin(1);
        recommendationConfig.setHorizonMax(10);
        recommendationConfig.setRecommendedInflation(0F);

        RecommendationConfig1 recommendationConfig1 = new RecommendationConfig1();
        recommendationConfig1.setInvMin(BigDecimal.ZERO);
        recommendationConfig1.setInvMax(BigDecimal.valueOf(1000L));
        recommendationConfig1.setDepMin(BigDecimal.ZERO);
        recommendationConfig1.setDepMax(BigDecimal.valueOf(1000L));
        recommendationConfig1.setHorizonMin(1);
        recommendationConfig1.setHorizonMax(10);
        recommendationConfig1.setRecommendedInflation(0F);
        GoalAccumulationRecommendationRequest goalAccumulationRecommendationRequest = new GoalAccumulationRecommendationRequest();
        goalAccumulationRecommendationRequest.setPRet(Arrays.asList( 0.09F));
        goalAccumulationRecommendationRequest.setPRisk(Arrays.asList(0.05F));
        goalAccumulationRecommendationRequest.setCurrInv(BigDecimal.valueOf(10000L));
        goalAccumulationRecommendationRequest.setHorizon(5);
        goalAccumulationRecommendationRequest.setHorizonFrequency(GoalAccumulationRecommendationRequest.HorizonFrequencyEnum.YEAR);
        goalAccumulationRecommendationRequest.setGoalConfig(goalConfig);
        goalAccumulationRecommendationRequest.setDepositConfig(Arrays.asList(goalDepositConfig));
        goalAccumulationRecommendationRequest.setRecommendationConfig(recommendationConfig1);
        goalAccumulationRecommendationRequest.setRecommendType(GoalAccumulationRecommendationRequest.RecommendTypeEnum.RECURRING);
        goalAccumulationRecommendationRequest.setConfTgt(0.9F);
        goalAccumulationRecommendationRequest.setN(1000);
        goalAccumulationRecommendationRequest.setRemoveOutliers(Boolean.TRUE);
        goalAccumulationRecommendationRequest.setThreshType(GoalAccumulationRecommendationRequest.ThreshTypeEnum.PERC);
        goalAccumulationRecommendationRequest.setThresh(BigDecimal.ZERO);
        goalAccumulationRecommendationRequest.setWithdrawalTax(0F);
        goalAccumulationRecommendationRequest.setTradingDaysPerYear(252);
        goalAccumulationRecommendationRequest.setAdjustForCompounding(Boolean.FALSE);
        goalAccumulationRecommendationRequest.setCompoundingRate(0F);
        goalAccumulationRecommendationRequest.setCreateLog(Boolean.FALSE);
        Map<String, Object> goalAccumulationRecommendationResponse = goalsApi.goalAccumulationRecommendation(goalAccumulationRecommendationRequest);
        System.out.println(goalAccumulationRecommendationResponse);
api_instance = proton_api.GoalsApi(proton_api.ApiClient(configuration))
goal_config = proton_api.GoalConfig(goal_amount=25000, goal_inflation=0)
accumulation_goal_deposit_config = proton_api.AccumulationGoalDepositConfig(
    dep_amount=2000, dep_start_reference='a_start', dep_start_period=0, dep_end_reference='a_start',
    dep_end_period=3, dep_inflation=0
)
recommendation_config = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

recommendation_config1 = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

goal_accumulation_recommendation_request = proton_api.GoalAccumulationRecommendationRequest(
    p_ret=[0.09], p_risk=[0.05], curr_inv=10000, horizon=5, horizon_frequency='year', goal_config=goal_config,
    deposit_config=[accumulation_goal_deposit_config], recommendation_config=recommendation_config1,
    recommend_type='recurring',
    conf_tgt=0.09, n=1000, remove_outliers=True, thresh_type='perc', thresh=0, withdrawal_tax=0,
    trading_days_per_year=252,
    adjust_for_compounding=False, compounding_rate=0, create_log=False
)
try:
    # GoalApi - Goal Accumulation Recommendation
    api_response = api_instance.goal_accumulation_recommendation(goal_accumulation_recommendation_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling GoalApi->goal_accumulation_recommendation: %s\n" % e)
api_instance = ProtonApi::GoalsApi.new
# AccumulationGoalDepositConfig
accumulationDepositConfig = ProtonApi::AccumulationGoalDepositConfig.new
accumulationDepositConfig.dep_amount = 2000
accumulationDepositConfig.dep_start_reference = "a_start"
accumulationDepositConfig.dep_start_period = 0
accumulationDepositConfig.dep_end_reference = "a_start"
accumulationDepositConfig.dep_end_period = 3
accumulationDepositConfig.dep_frequency = "year"
accumulationDepositConfig.dep_inflation = 0
# Recommendation Config
recommendationConfig = ProtonApi::RecommendationConfig.new
recommendationConfig.recommend = true
recommendationConfig.inv_max = 1000
recommendationConfig.inv_min = 0
recommendationConfig.dep_min = 0
recommendationConfig.dep_max = 1000
recommendationConfig.horizon_min = 1
recommendationConfig.horizon_max = 10
recommendationConfig.recommended_inflation = 0
# Goal Config
goalConfig = ProtonApi::GoalConfig.new
goalConfig.goal_amount = 25000
goalConfig.goal_inflation = 0
# wConfig
wConfig = ProtonApi::WConfig1.new
wConfig.w_max_major = 1
wConfig.w_max_minor = 1
wConfig.w_min_major = 0
wConfig.w_min_minor = 0
wConfig.cash_amount = 0
# w_asset_config
w_asset_config = {
    "US_Equities" => 1,
    "Fixed_Income" => 1,
    "Intl_Equities" => 1
}
goal_accumulation_recommendation_request = ProtonApi::GoalAccumulationRecommendationRequest.new
begin
  goal_accumulation_recommendation_request.p_ret = [0.09]
  goal_accumulation_recommendation_request.p_risk = [0.05]
  goal_accumulation_recommendation_request.trading_days_per_year = 252
  goal_accumulation_recommendation_request.horizon = 5
  goal_accumulation_recommendation_request.horizon_frequency = "year"
  goal_accumulation_recommendation_request.goal_config = goalConfig
  goal_accumulation_recommendation_request.recommendation_config = recommendationConfig
  goal_accumulation_recommendation_request.curr_inv = 10000
  goal_accumulation_recommendation_request.recommend_type = "recurring"
  goal_accumulation_recommendation_request.conf_tgt = 0.9
  goal_accumulation_recommendation_request.n = 1000
  goal_accumulation_recommendation_request.remove_outliers = true
  goal_accumulation_recommendation_request.thresh_type = "perc"
  goal_accumulation_recommendation_request.thresh = 0
  goal_accumulation_recommendation_request.withdrawal_tax = 0.0
  goal_accumulation_recommendation_request.adjust_for_compounding = false
  goal_accumulation_recommendation_request.compounding_rate = 0.0
  goal_accumulation_recommendation_request.create_log = false
  accumulation_allocation_recomendation_response = api_instance.goal_accumulation_recommendation(goal_accumulation_recommendation_request)
  p accumulation_allocation_recomendation_response
rescue ProtonApi::ApiError => e
  puts "Exception when calling goal_Accumulation_Recommendation_Request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\GoalsApi(
    new GuzzleHttp\Client(),
    $config
);
$goalAccumulationRecommendationRequest = new com\hydrogen\proton\Model\GoalAccumulationRecommendationRequest();
try {

    $goalAccumulationRecommendationRequest->setPRet(array(0.09));
    $goalAccumulationRecommendationRequest->setPRisk(array(0.05));
    $goalAccumulationRecommendationRequest->setTradingDaysPerYear(252);
    $goalAccumulationRecommendationRequest->setHorizon(5);
    $goalAccumulationRecommendationRequest->setHorizonFrequency("year");
    $goal_config = new \com\hydrogen\proton\Model\GoalConfig();
    $goal_config->setGoalAmount(250000);
    $goal_config->setGoalInflation(0.0);
    $goalAccumulationRecommendationRequest->setGoalConfig($goal_config);
    $recommendationConfig = new \com\hydrogen\proton\Model\RecommendationConfig1();
    $recommendationConfig->setInvMin(0);
    $recommendationConfig->setInvMax(1000);
    $recommendationConfig->setDepMin(0);
    $recommendationConfig->setDepMax(1000);
    $recommendationConfig->setHorizonMin(1);
    $recommendationConfig->setHorizonMax(10);
    $recommendationConfig->setRecommendedInflation(0.0);
    $goalAccumulationRecommendationRequest->setRecommendationConfig($recommendationConfig);

    $depositConfig = new \com\hydrogen\proton\Model\AccumulationGoalDepositConfig();
    $depositConfig->setDepStartReference("a_start");
    $depositConfig->setDepStartPeriod(0) ;
    $depositConfig->setDepEndReference("a_start");
    $depositConfig->setDepEndPeriod(3);
    $depositConfig->setDepAmount(2000) ;
    $depositConfig->setDepInflation(0);
    $goalAccumulationRecommendationRequest->setDepositConfig(array($depositConfig));

    $goalAccumulationRecommendationRequest->setCurrInv(10000);
    $goalAccumulationRecommendationRequest->setRecommendType("recurring");
    $goalAccumulationRecommendationRequest->setConfTgt(0.9);
    $goalAccumulationRecommendationRequest->setN(1000);
    $goalAccumulationRecommendationRequest->setRemoveOutliers(true);
    $goalAccumulationRecommendationRequest->setThreshType("perc");
    $goalAccumulationRecommendationRequest->setThresh(0);
    $goalAccumulationRecommendationRequest->setWithdrawalTax(0.0);
    $goalAccumulationRecommendationRequest->setAdjustForCompounding(false);
    $goalAccumulationRecommendationRequest->setCompoundingRate(0.0);
    $goalAccumulationRecommendationRequest->setCreateLog(false);
    $result = $apiInstance->goalAccumulationRecommendation($goalAccumulationRecommendationRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling GoalsApi->goalAccumulationRecommendation: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.GoalsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.GoalsApi();
    var goalAccumulationRecommendationRequest = new HydrogenProtonApi.GoalAccumulationRecommendationRequest();
    goalAccumulationRecommendationRequest.p_ret = [0.09];
    goalAccumulationRecommendationRequest.p_risk = [0.05];
    goalAccumulationRecommendationRequest.curr_inv = 10000;
    goalAccumulationRecommendationRequest.trading_days_per_year = 252;
    goalAccumulationRecommendationRequest.horizon = 5;
    goalAccumulationRecommendationRequest.horizon_frequency = "year";
    goalAccumulationRecommendationRequest.goal_config = {
        "goal_amount": 25000,
        "goal_inflation": 0.0
    };
    goalAccumulationRecommendationRequest.recommendation_config = {
        "inv_min": 0,
        "inv_max": 1000,
        "dep_min": 0,
        "dep_max": 1000,
        "horizon_min": 1,
        "horizon_max": 10,
        "recommended_inflation": 0.0
    };
    goalAccumulationRecommendationRequest.recommend_type = "recurring";
    goalAccumulationRecommendationRequest.conf_tgt = 0.9;
    goalAccumulationRecommendationRequest.n = 1000;
    goalAccumulationRecommendationRequest.remove_outliers = "true";
    goalAccumulationRecommendationRequest.thresh_type = "perc";
    goalAccumulationRecommendationRequest.thresh = 0;
    goalAccumulationRecommendationRequest.withdrawal_tax = 0.0;
    goalAccumulationRecommendationRequest.adjust_for_compounding = "false";
    goalAccumulationRecommendationRequest.compounding_rate = 0.0;
    goalAccumulationRecommendationRequest.createLog = false;
    api.goalAccumulationRecommendation(goalAccumulationRecommendationRequest, callback)

ARGUMENTS

Parameter Description
p_ret
array, required
The annual portfolio return per period. The length of the array must be less than or equal to horizon. If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods.
p_risk
array, required
The annual portfolio standard deviation per period. The length of the array must be less than or equal to horizon. If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_risk of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods.
curr_inv
float, conditional requirement
The current amount invested toward the goal.
horizon
integer, conditional requirement
The goal horizon, with a frequency defined by horizon_frequency. For example, for a client that is looking to make a major purchase in 30 years, use horizon = 30.
horizon_frequency
string, conditional requirement
The frequency in relation to the number defined in horizon, and at which to run the simulation. Must be one of the following: year, quarter, month, week, day.
goal_config
map, required
Information to configure the accumulation goal amount.
      goal_amount
      string, conditional requirement
The target goal amount, in today’s dollars.
      goal_inflation
      integer
The annualized inflation rate for goal_amount. Defaults to 0.
deposit_config
array(map)
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below.
      dep_start_reference
      string
The reference for the starting point of the deposit. May be a_start or a_end, which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_start.
      dep_start_period
      integer
The starting period for the deposit, relative to dep_start_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_end_reference
      string
The reference for the ending point of the deposit. May be a_start or a_end, which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_end.
      dep_end_period
      integer
The ending period for the deposit, relative to dep_end_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_amount
      float
The deposit amount, in today’s dollars. Defaults to 0.
      dep_frequency
      string
The frequency of the deposit. Must be one of the following: year, quarter, month, week, day. Defaults to year.
      dep_inflation
      float
The annualized inflation rate for the deposit. Defaults to 0.
recommendation_config
map
Information to configure the goal recommendation engine, including the fields shown below.
      inv_min
      float
The lower bound for one-time deposit recommendations. Defaults to 0.
      inv_max
      float
The upper bound for one-time deposit recommendations. Defaults to goal_amount.
      dep_min
      float
The lower bound for recurring deposit recommendations. Defaults to 0.
      dep_max
      float
The upper bound for recurring deposit recommendations. Defaults to goal_amount divided by horizon.
      horizon_min
      integer
The minimum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 1.
      horizon_max
      integer
The maximum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 64.
      recommended_inflation
      float
The annualized inflation rate attributed to a recommended recurring deposit.
recommend_type
string
The type of recommended action. Value may be recurring, one-time, combo, or horizon. recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon.
conf_tgt
float
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90.
n
integer
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000.
remove_outliers
boolean
If true, remove outlying results. If true, outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true.
thresh_type
string
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc.
thresh
float
The goal deviation threshold value, corresponding to thresh_type. Defaults to 0.
withdrawal_tax
float
The tax rate to apply to all withdrawals. Defaults to 0.
trading_days_per_year
integer
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day. Defaults to 252.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.
client_id
UUID, conditional requirement
The ID of a Nucleus client used to derive one or more of the following: curr_inv, horizon, horizon_frequency, and goal_config.goal_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
goal_id
UUID, conditional requirement
The ID of a Nucleus goal used to derive one or more of the following:curr_inv, horizon, horizon_frequency, and goal_config.goal_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
create_log
boolean
If true, a record of this Proton request URL, request body, response body, and Nucleus UUID(s), where applicable, will be stored in Electron as an audit log, and the resulting audit_log_id will be returned in the Proton response. Defaults to false.

Example Response

{
    "on_track": true,
    "progress": 0.4,
    "goal_probability": 0.915,
    "goal_achievement_score": 100,
    "action": [
        {
            "value": 796.875,
            "freq_unit": "year",
            "value_type": "recurring_deposit"
        }
    ],
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_deposit": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 0,
            "cumulative_deposits": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 10000
        },
        "1": {
            "period_earnings": 271.88,
            "period_deposit": 2796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 271.88,
            "cumulative_deposits": 2796.88,
            "cumulative_withdrawals": 0,
            "ending_balance": 13068.75
        },
        "2": {
            "period_earnings": 813.47,
            "period_deposit": 2796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 1085.35,
            "cumulative_deposits": 5593.75,
            "cumulative_withdrawals": 0,
            "ending_balance": 16679.1
        },
        "3": {
            "period_earnings": 1057.48,
            "period_deposit": 2796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 2142.83,
            "cumulative_deposits": 8390.62,
            "cumulative_withdrawals": 0,
            "ending_balance": 20533.46
        },
        "4": {
            "period_earnings": 1364.75,
            "period_deposit": 796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 3507.59,
            "cumulative_deposits": 9187.5,
            "cumulative_withdrawals": 0,
            "ending_balance": 22695.09
        },
        "5": {
            "period_earnings": 1735.93,
            "period_deposit": 796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 5243.52,
            "cumulative_deposits": 9984.38,
            "cumulative_withdrawals": 0,
            "ending_balance": 25227.89
        }
    },
    "adjusted_goal_amount": 25000,
    "final_balance": 25227.89
}

RESPONSE

Field Description
on_track If true, the goal is on track.
progress The goal progress percentage, defined as the current invested amount divided by the target goal_amount.
goal_probability The probability of achieving the goal with the given portfolio.
goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
action The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits.
      value The value of the recommended action.
      freq_unit The frequency unit of value.
      value_type The type of recommendation being made.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      period_deposit The deposit made for this period in the accumulation phase.
      period_withdrawal The withdrawal made for this period.
      cumulative_earnings The cumulative investment earnings made up to and including this period.
      cumulative_deposit The cumulative deposits made up to and including this period for the accumulation phase.
      cumulative_withdrawals The cumulative withdrawals made up to and including this period.
      ending_balance The ending balance, inclusive of earnings and contributions for the current period.
adjusted_goal_amount The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold.
final_balance The projected final balance from return_details.
audit_log_id The unique id of the audit log record created in Electron. Only returned when create_log = true.

NUCLEUS DATA DEPENDENCIES

Accumulation Goal Status

This service analyzes the state of expected goal achievement for an accumulation goal, based on the current goal configuration and context. In addition to a raw indication of whether a goal is on or off track, the service provides other metrics for advanced analysis. This framework also has built-in support for a goal recommendation engine, which recommends actions that may be taken to increase the expected goal achievement probability if a goal is off track.

HTTP REQUEST

POST /goal_accumulation/status

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "p_ret": [0.09],
        "p_risk": [0.05],
        "trading_days_per_year": 252,
        "horizon": 5,
        "horizon_frequency": "year",
        "deposit_config": [
            {
                "dep_start_reference": "a_start",
                "dep_start_period": 0,
                "dep_end_reference": "a_start",
                "dep_end_period": 3,
                "dep_amount": 2000,
                "dep_frequency": "year",
                "dep_inflation": 0.0
            }
        ],
        "goal_config": {
            "goal_amount": 25000,
            "goal_inflation": 0.0
        },
        "recommendation_config": {
            "recommend": true,
            "inv_min": 0,
            "inv_max": 1000,
            "dep_min": 0,
            "dep_max": 1000,
            "horizon_min": 1,
            "horizon_max": 10,
            "recommended_inflation": 0.0
        },
        "curr_inv": 10000,
        "recommend_type": "recurring",
        "conf_tgt": 0.9,
        "n": 1000,
        "remove_outliers": true,
        "thresh_type": "perc",
        "thresh": 0,
        "withdrawal_tax": 0.0,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0
    }' "https://api.hydrogenplatform.com/proton/v1/goal_accumulation/status"
GoalsApi goalsApi = new GoalsApi();
        GoalConfig goalConfig = new GoalConfig();
        goalConfig.setGoalAmount(BigDecimal.valueOf(25000L));
        goalConfig.setGoalInflation(0F);
        AccumulationGoalDepositConfig goalDepositConfig = new AccumulationGoalDepositConfig();
        goalDepositConfig.setDepAmount(BigDecimal.valueOf(2000));
        goalDepositConfig.setDepStartReference(AccumulationGoalDepositConfig.DepStartReferenceEnum.START);
        goalDepositConfig.setDepStartPeriod(0);
        goalDepositConfig.setDepEndReference(AccumulationGoalDepositConfig.DepEndReferenceEnum.START);
        goalDepositConfig.setDepEndPeriod(3);
        goalDepositConfig.setDepInflation(0F);


        RecommendationConfig recommendationConfig = new RecommendationConfig();
        recommendationConfig.setRecommend(true);
        recommendationConfig.setInvMin(BigDecimal.ZERO);
        recommendationConfig.setInvMax(BigDecimal.valueOf(1000L));
        recommendationConfig.setDepMin(BigDecimal.ZERO);
        recommendationConfig.setDepMax(BigDecimal.valueOf(1000L));
        recommendationConfig.setHorizonMin(1);
        recommendationConfig.setHorizonMax(10);
        recommendationConfig.setRecommendedInflation(0F);
        RecommendationConfig1 recommendationConfig1 = new RecommendationConfig1();
        recommendationConfig1.setInvMin(BigDecimal.ZERO);
        recommendationConfig1.setInvMax(BigDecimal.valueOf(1000L));
        recommendationConfig1.setDepMin(BigDecimal.ZERO);
        recommendationConfig1.setDepMax(BigDecimal.valueOf(1000L));
        recommendationConfig1.setHorizonMin(1);
        recommendationConfig1.setHorizonMax(10);
        recommendationConfig1.setRecommendedInflation(0F);
        GoalAccumulationStatusRequest goalAccumulationStatusRequest = new GoalAccumulationStatusRequest();
        goalAccumulationStatusRequest.setPRet(Arrays.asList(0.09F));
        goalAccumulationStatusRequest.setPRisk(Arrays.asList(0.05F));
        goalAccumulationStatusRequest.setCurrInv(BigDecimal.valueOf(1000L));
        goalAccumulationStatusRequest.setHorizon(5);
        goalAccumulationStatusRequest.setHorizonFrequency(GoalAccumulationStatusRequest.HorizonFrequencyEnum.YEAR);
        goalAccumulationStatusRequest.setGoalConfig(goalConfig);
        goalAccumulationStatusRequest.setDepositConfig(Arrays.asList(goalDepositConfig));
        goalAccumulationStatusRequest.setRecommendationConfig(recommendationConfig);
        goalAccumulationStatusRequest.setRecommendType(GoalAccumulationStatusRequest.RecommendTypeEnum.RECURRING);
        goalAccumulationStatusRequest.setConfTgt(0.9F);
        goalAccumulationStatusRequest.setN(1000);
        goalAccumulationStatusRequest.setRemoveOutliers(Boolean.TRUE);
        goalAccumulationStatusRequest.setThreshType(GoalAccumulationStatusRequest.ThreshTypeEnum.PERC
        );
        goalAccumulationStatusRequest.setThresh(BigDecimal.ZERO);
        goalAccumulationStatusRequest.setWithdrawalTax(0F);
        goalAccumulationStatusRequest.setTradingDaysPerYear(252);
        goalAccumulationStatusRequest.setAdjustForCompounding(Boolean.FALSE);
        goalAccumulationStatusRequest.setCompoundingRate(0F);
        goalAccumulationStatusRequest.setCreateLog(Boolean.FALSE);
        Map<String, Object> goalAccumulationStatusResponse = goalsApi.goalAccumulationStatus(goalAccumulationStatusRequest);
        System.out.println(goalAccumulationStatusResponse);
api_instance = proton_api.GoalsApi(proton_api.ApiClient(configuration))
goal_config = proton_api.GoalConfig(goal_amount=25000, goal_inflation=0)
accumulation_goal_deposit_config = proton_api.AccumulationGoalDepositConfig(
    dep_amount=2000, dep_start_reference='a_start', dep_start_period=0, dep_end_reference='a_start',
    dep_end_period=3, dep_inflation=0
)
recommendation_config = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

recommendation_config1 = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

goal_accumulation_status_request = proton_api.GoalAccumulationStatusRequest(
    p_ret=[0.09], p_risk=[0.05], curr_inv=1000, horizon=5, horizon_frequency='year', goal_config=goal_config,
    deposit_config=[accumulation_goal_deposit_config],
    recommendation_config=recommendation_config, recommend_type='recurring', conf_tgt=0.09, n=1000,
    remove_outliers=True, thresh_type='perc',
    thresh=0, withdrawal_tax=0, trading_days_per_year=252, adjust_for_compounding=False, compounding_rate=0,
    create_log=False
)
try:
    # GoalApi - Goal Accumulation Status
    api_response = api_instance.goal_accumulation_status(goal_accumulation_status_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling GoalApi->goal_accumulation_status: %s\n" % e)
api_instance = ProtonApi::GoalsApi.new
# AccumulationGoalDepositConfig
accumulationDepositConfig = ProtonApi::AccumulationGoalDepositConfig.new
accumulationDepositConfig.dep_amount = 2000
accumulationDepositConfig.dep_start_reference = "a_start"
accumulationDepositConfig.dep_start_period = 0
accumulationDepositConfig.dep_end_reference = "a_start"
accumulationDepositConfig.dep_end_period = 3
accumulationDepositConfig.dep_frequency = "year"
accumulationDepositConfig.dep_inflation = 0
# Recommendation Config
recommendationConfig = ProtonApi::RecommendationConfig.new
recommendationConfig.recommend = true
recommendationConfig.inv_max = 1000
recommendationConfig.inv_min = 0
recommendationConfig.dep_min = 0
recommendationConfig.dep_max = 1000
recommendationConfig.horizon_min = 1
recommendationConfig.horizon_max = 10
recommendationConfig.recommended_inflation = 0
# Goal Config
goalConfig = ProtonApi::GoalConfig.new
goalConfig.goal_amount = 25000
goalConfig.goal_inflation = 0
# wConfig
wConfig = ProtonApi::WConfig1.new
wConfig.w_max_major = 1
wConfig.w_max_minor = 1
wConfig.w_min_major = 0
wConfig.w_min_minor = 0
wConfig.cash_amount = 0
# w_asset_config
w_asset_config = {
    "US_Equities" => 1,
    "Fixed_Income" => 1,
    "Intl_Equities" => 1
}
goalAccumulationStatusRequest = ProtonApi::GoalAccumulationStatusRequest.new

begin
  goalAccumulationStatusRequest.p_ret = [0.09]
  goalAccumulationStatusRequest.p_risk = [0.05]
  goalAccumulationStatusRequest.trading_days_per_year = 252
  goalAccumulationStatusRequest.horizon = 5
  goalAccumulationStatusRequest.horizon_frequency = "year"
  goalAccumulationStatusRequest.deposit_config = [accumulationDepositConfig]
  goalAccumulationStatusRequest.goal_config = goalConfig
  goalAccumulationStatusRequest.recommendation_config = recommendationConfig
  goalAccumulationStatusRequest.curr_inv = 10000
  goalAccumulationStatusRequest.recommend_type = "recurring"
  goalAccumulationStatusRequest.conf_tgt = 0.9
  goalAccumulationStatusRequest.n = 1000
  goalAccumulationStatusRequest.remove_outliers = true
  goalAccumulationStatusRequest.thresh_type = "perc"
  goalAccumulationStatusRequest.thresh = 0
  goalAccumulationStatusRequest.withdrawal_tax = 0.0
  goalAccumulationStatusRequest.adjust_for_compounding = false
  goalAccumulationStatusRequest.compounding_rate = 0.0
  goalAccumulationStatusRequest.create_log = false
  goalAccumulationStatusResponse = api_instance.goal_accumulation_status(goalAccumulationStatusRequest)
  p goalAccumulationStatusResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling goal_accumulation_status_request_request #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\GoalsApi(
    new GuzzleHttp\Client(),
    $config
);
$goalAccumulationStatusRequest = new com\hydrogen\proton\Model\GoalAccumulationStatusRequest();
try {

    $goalAccumulationStatusRequest->setPRet(array(0.09));
    $goalAccumulationStatusRequest->setPRisk(array(0.05));
    $goalAccumulationStatusRequest->setTradingDaysPerYear(252);
    $goalAccumulationStatusRequest->setHorizon(5);
    $goalAccumulationStatusRequest->setHorizonFrequency("year");
    $depositConfigStatus = new com\hydrogen\proton\Model\AccumulationGoalDepositConfig();
    $depositConfigStatus->setDepStartReference("a_start");
    $depositConfigStatus->setDepStartPeriod(0);
    $depositConfigStatus->setDepEndReference("a_start");
    $depositConfigStatus->setDepEndPeriod(3);
    $depositConfigStatus->setDepAmount(2000);
    $depositConfigStatus->setDepFrequency('year');
    $depositConfigStatus->setDepInflation(0.0);
    $goalAccumulationStatusRequest->setDepositConfig(array($depositConfigStatus));

    $goalConfigstatus = new com\hydrogen\proton\Model\GoalConfig();
    $goalConfigstatus->setGoalAmount(25000);
    $goalConfigstatus->setGoalInflation(0.0);
    $goalAccumulationStatusRequest->setGoalConfig($goalConfigstatus);

    $recommendationConfigStatus = new com\hydrogen\proton\Model\RecommendationConfig();
    $recommendationConfigStatus->setRecommend(true);
    $recommendationConfigStatus->setInvMin(0);
    $recommendationConfigStatus->setInvMax(1000);
    $recommendationConfigStatus->setDepMin(0);
    $recommendationConfigStatus->setDepMax(1000);
    $recommendationConfigStatus->setHorizonMin(1);
    $recommendationConfigStatus->setHorizonMax(10);
    $recommendationConfigStatus->setRecommendedInflation(0.0);
    $goalAccumulationStatusRequest->setRecommendationConfig($recommendationConfigStatus);

    $goalAccumulationStatusRequest->setCurrInv(10000);
    $goalAccumulationStatusRequest->setRecommendType("recurring");
    $goalAccumulationStatusRequest->setConfTgt(0.9);
    $goalAccumulationStatusRequest->setN(1000);
    $goalAccumulationStatusRequest->setRemoveOutliers(true);
    $goalAccumulationStatusRequest->setThreshType("perc");
    $goalAccumulationStatusRequest->setThresh(0);
    $goalAccumulationStatusRequest->setWithdrawalTax(0.0);
    $goalAccumulationStatusRequest->setAdjustForCompounding(false);
    $goalAccumulationStatusRequest->setCompoundingRate(0.0);
    $goalAccumulationStatusRequest->setCreateLog(false);

    $result = $apiInstance->goalAccumulationStatus($goalAccumulationStatusRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling GoalsApi->goalAccumulationStatus: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.GoalsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.GoalsApi();
    var goalAccumulationStatusRequestRequest = new HydrogenProtonApi.GoalAccumulationStatusRequest();
    goalAccumulationStatusRequestRequest.p_ret = [0.09];
    goalAccumulationStatusRequestRequest.p_risk = [0.05];
    goalAccumulationStatusRequestRequest.trading_days_per_year = 252;
    goalAccumulationStatusRequestRequest.horizon = 5;
    goalAccumulationStatusRequestRequest.horizon_frequency = "year";
    goalAccumulationStatusRequestRequest.deposit_config =[
        {
            "dep_start_reference": "a_start",
            "dep_start_period": 0,
            "dep_end_reference": "a_start",
            "dep_end_period": 3,
            "dep_amount": 2000,
            "dep_frequency": "year",
            "dep_inflation": 0.0
        }
    ];
    goalAccumulationStatusRequestRequest.goal_config= {
        "goal_amount": 25000,
        "goal_inflation": 0.0
    };
    goalAccumulationStatusRequestRequest.recommendation_config= {
        "recommend": true,
        "inv_min": 0,
        "inv_max": 1000,
        "dep_min": 0,
        "dep_max": 1000,
        "horizon_min": 1,
        "horizon_max": 10,
        "recommended_inflation": 0.0
    };
    goalAccumulationStatusRequestRequest.curr_inv = 10000;
    goalAccumulationStatusRequestRequest.recommend_type = "recurring";
    goalAccumulationStatusRequestRequest.conf_tgt = 0.9;
    goalAccumulationStatusRequestRequest.n = 1000;
    goalAccumulationStatusRequestRequest.remove_outliers = "true";
    goalAccumulationStatusRequestRequest.thresh_type = "perc";
    goalAccumulationStatusRequestRequest.thresh = 0;
    goalAccumulationStatusRequestRequest.withdrawal_tax = 0.0;
    goalAccumulationStatusRequestRequest.adjust_for_compounding = "false";
    goalAccumulationStatusRequestRequest.compounding_rate =0.0;
    goalAccumulationStatusRequestRequest.createLog = false
    api.goalAccumulationStatus(goalAccumulationStatusRequestRequest, callback)

ARGUMENTS

Parameter Description
p_ret
array, required
The annual portfolio return per period. The length of the array must be less than or equal to horizon. If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods.
p_risk
array, required
The annual portfolio standard deviation per period. The length of the array must be less than or equal to horizon. If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_risk of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods.
curr_inv
float, conditional requirement
The current amount invested toward the goal.
horizon
integer, conditional requirement
The goal horizon, with a frequency defined by horizon_frequency. For example, for a client that is looking to make a major purchase in 30 years, use horizon = 30.
horizon_frequency
string, conditional requirement
The frequency in relation to the number defined in horizon, and at which to run the simulation. Must be one of the following: year, quarter, month, week, day.
goal_config
map, required
Information to configure the accumulation goal amount.
      goal_amount
      string, conditional requirement
The target goal amount, in today’s dollars.
      goal_inflation
      integer
The annualized inflation rate for goal_amount. Defaults to 0.
deposit_config
array(map)
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below.
      dep_start_reference
      string
The reference for the starting point of the deposit. May be a_start or a_end, which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_start.
      dep_start_period
      integer
The starting period for the deposit, relative to dep_start_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_end_reference
      string
The reference for the ending point of the deposit. May be a_start or a_end, which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_end.
      dep_end_period
      integer
The ending period for the deposit, relative to dep_end_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_amount
      float
The deposit amount, in today’s dollars. Defaults to 0.
      dep_frequency
      string
The frequency of the deposit. Must be one of the following: year, quarter, month, week, day. Defaults to year.
      dep_inflation
      float
The annualized inflation rate for the deposit. Defaults to 0.
recommendation_config
map
Information to configure the goal recommendation engine, including the fields shown below.
      recommend
      boolean
If true, generate a recommended action to improve goal probability. Recommendations are only generated if a goal is off-track. Defaults to true.
      inv_min
      float
The lower bound for one-time deposit recommendations. Defaults to 0.
      inv_max
      float
The upper bound for one-time deposit recommendations. Defaults to goal_amount.
      dep_min
      float
The lower bound for recurring deposit recommendations. Defaults to 0.
      dep_max
      float
The upper bound for recurring deposit recommendations. Defaults to goal_amount divided by horizon.
      horizon_min
      integer
The minimum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 1.
      horizon_max
      integer
The maximum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 64.
      recommended_inflation
      float
The annualized inflation rate attributed to a recommended recurring deposit.
recommend_type
string
The type of recommended action. Value may be recurring, one-time, combo, or horizon. recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon.
conf_tgt
float
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90.
n
integer
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000.
remove_outliers
boolean
If true, remove outlying results. If true, outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true.
thresh_type
string
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc.
thresh
float
The goal deviation threshold value, corresponding to thresh_type. Defaults to 0.
withdrawal_tax
float
The tax rate to apply to all withdrawals. Defaults to 0.
trading_days_per_year
integer
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day. Defaults to 252.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.
client_id
UUID, conditional requirement
The ID of a Nucleus client used to derive one or more of the following: curr_inv, horizon, horizon_frequency, and goal_config.goal_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
goal_id
UUID, conditional requirement
The ID of a Nucleus goal used to derive one or more of the following:curr_inv, horizon, horizon_frequency, and goal_config.goal_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
create_log
boolean
If true, a record of this Proton request URL, request body, response body, and Nucleus UUID(s), where applicable, will be stored in Electron as an audit log, and the resulting audit_log_id will be returned in the Proton response. Defaults to false.

Example Response

{
    "current_status": {
        "on_track": false,
        "progress": 0.4,
        "goal_probability": 0.1638,
        "goal_achievement_score": 18,
        "return_details": {
            "0": {
                "period_earnings": 0,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 0,
                "cumulative_deposits": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 10000
            },
            "1": {
                "period_earnings": 274.26,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 274.26,
                "cumulative_deposits": 2000,
                "cumulative_withdrawals": 0,
                "ending_balance": 12274.26
            },
            "2": {
                "period_earnings": 665.94,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 940.19,
                "cumulative_deposits": 4000,
                "cumulative_withdrawals": 0,
                "ending_balance": 14940.19
            },
            "3": {
                "period_earnings": 954.05,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 1894.25,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 17894.25
            },
            "4": {
                "period_earnings": 1068.64,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 2962.89,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 18962.89
            },
            "5": {
                "period_earnings": 1479.72,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 4442.61,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 20442.61
            }
        },
        "adjusted_goal_amount": 25000,
        "final_balance": 20442.61
    },
    "recommended_status": {
        "on_track": true,
        "progress": 0.4,
        "goal_probability": 0.9025,
        "goal_achievement_score": 100,
        "action": [
            {
                "value": 781.25,
                "freq_unit": "year",
                "value_type": "recurring_deposit"
            }
        ],
        "return_details": {
            "0": {
                "period_earnings": 0,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 0,
                "cumulative_deposits": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 10000
            },
            "1": {
                "period_earnings": 302.11,
                "period_deposit": 2781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 302.11,
                "cumulative_deposits": 2781.25,
                "cumulative_withdrawals": 0,
                "ending_balance": 13083.36
            },
            "2": {
                "period_earnings": 749.04,
                "period_deposit": 2781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 1051.14,
                "cumulative_deposits": 5562.5,
                "cumulative_withdrawals": 0,
                "ending_balance": 16613.64
            },
            "3": {
                "period_earnings": 1059.19,
                "period_deposit": 2781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 2110.34,
                "cumulative_deposits": 8343.75,
                "cumulative_withdrawals": 0,
                "ending_balance": 20454.09
            },
            "4": {
                "period_earnings": 1443.06,
                "period_deposit": 781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 3553.4,
                "cumulative_deposits": 9125,
                "cumulative_withdrawals": 0,
                "ending_balance": 22678.4
            },
            "5": {
                "period_earnings": 1579.8,
                "period_deposit": 781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 5133.2,
                "cumulative_deposits": 9906.25,
                "cumulative_withdrawals": 0,
                "ending_balance": 25039.45
            }
        },
        "adjusted_goal_amount": 25000,
        "final_balance": 25039.45
    }
}

RESPONSE

Field Description
current_status The current status of the goal.
      on_track If true, the goal is on track.
      progress The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon.
      goal_probability The probability of achieving the goal with the given portfolio.
      goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
      return_details Portfolio return information over the length of the horizon, broken down by period.
            period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
            period_deposit The deposit made for this period in the accumulation phase.
            period_withdrawal The withdrawal made for this period.
            cumulative_earnings The cumulative investment earnings made up to and including this period.
            cumulative_deposit The cumulative deposits made up to and including this period for the decumulation phase.
            cumulative_withdrawals The cumulative withdrawals made up to and including this period.
            ending_balance The ending balance, inclusive of earnings and contributions for the current period.
      adjusted_goal_amount The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold.
      final_balance The projected final balance from return_details.
recommended_status The goal status based on the provided recommendation.
      on_track If true, the goal is on track.
      progress The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon.
      goal_probability The probability of achieving the goal with the given portfolio.
      goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
      action The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits.
            value The value of the recommended action.
            freq_unit The frequency unit of value.
            value_type The type of recommendation being made.
      return_details Portfolio return information over the length of the horizon, broken down by period.
            period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
            period_deposit The deposit made for this period in the accumulation phase.
            period_withdrawal The withdrawal made for this period.
            cumulative_earnings The cumulative investment earnings made up to and including this period.
            cumulative_deposit The cumulative deposits made up to and including this period for the decumulation phase.
            cumulative_withdrawals The cumulative withdrawals made up to and including this period.
            ending_balance The ending balance, inclusive of earnings and contributions for the current period.
      adjusted_goal_amount The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold.
      final_balance The projected final balance from return_details.
audit_log_id The unique id of the audit log record created in Electron. Only returned when create_log = true.

NUCLEUS DATA DEPENDENCIES

Decumulation Goal Allocation

This service offers a framework to match a decumulation goal to an appropriate portfolio, with the ability to prioritize an investor’s risk appetite or prioritize the goal achievement. Allocations are selected from a universe based upon best fit for the selected priority, drawing from pre-defined portfolios and dynamically generated portfolios. This framework also has built-in support for a goal recommendation engine, which recommends actions that may be taken to increase the expected goal achievement probability if a goal cannot be achieved in the initially presented allocation context.

HTTP REQUEST

POST /goal_decumulation/allocation

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "allocation_method": "create",
        "allocation_priority": "goal",
        "allocations": [
            "406ec16e-ebae-4130-a6c0-1cacb72569a2",
            "740f6466-3300-4122-927d-4a691359fa32",
            "0a02058f-4046-48de-b3d2-aeefd6d4efac"
        ],
        "opt_config": {
            "tickers": ["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
            "min_assets": 6,
            "w_config": {
                "w_min_major": 0.05,
                "w_max_major": 1,
                "w_min_minor": 0.05,
                "w_max_minor": 0.1,
                "cash_amount": 0.0
            },
            "w_asset_config": {
                "US_Equities": 1.0,
                "Fixed_Income": 1.0,
                "Intl_Equities": 1.0,
                "EM_Equities": 1.0,
                "Commodities": 1.0
            },
            "sec_types": ["minor", "major","minor", "minor", "minor", "minor"],
            "start_date": "2016-01-01",
            "end_date": "2017-01-01"
        },
        "risk_score": 77,
        "trading_days_per_year": 252,
        "a_horizon": 3,
        "d_horizon": 2,
        "horizon_frequency": "year",
        "deposit_config": [
            {
                "dep_start_reference": "a_start",
                "dep_start_period": 0,
                "dep_end_reference": "a_start",
                "dep_end_period": 3,
                "dep_amount": 2000,
                "dep_frequency": "year",
                "dep_inflation": 0.0
            }
        ],
        "withdrawal_config": [
              {
                "with_amount": 11000,
                "with_start_reference": "a_end",
                "with_start_period": 0,
                "with_end_reference": "d_end",
                "with_end_period": 0,
                "with_frequency": "year",
                "with_inflation": 0.0
              }
        ],
        "recommendation_config": {
            "recommend": true,
            "inv_min": 0,
            "inv_max": 1000,
            "dep_min": 0,
            "dep_max": 1000,
            "horizon_min": 1,
            "horizon_max": 10,
            "recommended_inflation": 0.0
        },
        "curr_inv": 10000,
        "recommend_type": "recurring",
        "conf_tgt": 0.9,
        "n": 1000,
        "remove_outliers": true,
        "thresh_type": "perc",
        "thresh": 0,
        "withdrawal_tax": 0.0,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0,
        "use_proxy_data": false
    }' "https://api.hydrogenplatform.com/proton/v1/goal_decumulation/allocation"
GoalsApi goalsApi = new GoalsApi();
        GoalConfig goalConfig = new GoalConfig();
        goalConfig.setGoalAmount(BigDecimal.valueOf(25000L));
        goalConfig.setGoalInflation(0F);
        AccumulationGoalDepositConfig goalDepositConfig = new AccumulationGoalDepositConfig();
        goalDepositConfig.setDepAmount(BigDecimal.valueOf(2000));
        goalDepositConfig.setDepStartReference(AccumulationGoalDepositConfig.DepStartReferenceEnum.START);
        goalDepositConfig.setDepStartPeriod(0);
        goalDepositConfig.setDepEndReference(AccumulationGoalDepositConfig.DepEndReferenceEnum.START);
        goalDepositConfig.setDepEndPeriod(3);
        goalDepositConfig.setDepInflation(0F);


        RecommendationConfig recommendationConfig = new RecommendationConfig();
        recommendationConfig.setRecommend(true);
        recommendationConfig.setInvMin(BigDecimal.ZERO);
        recommendationConfig.setInvMax(BigDecimal.valueOf(1000L));
        recommendationConfig.setDepMin(BigDecimal.ZERO);
        recommendationConfig.setDepMax(BigDecimal.valueOf(1000L));
        recommendationConfig.setHorizonMin(1);
        recommendationConfig.setHorizonMax(10);
        recommendationConfig.setRecommendedInflation(0F);
        RecommendationConfig1 recommendationConfig1 = new RecommendationConfig1();
        recommendationConfig1.setInvMin(BigDecimal.ZERO);
        recommendationConfig1.setInvMax(BigDecimal.valueOf(1000L));
        recommendationConfig1.setDepMin(BigDecimal.ZERO);
        recommendationConfig1.setDepMax(BigDecimal.valueOf(1000L));
        recommendationConfig1.setHorizonMin(1);
        recommendationConfig1.setHorizonMax(10);
        recommendationConfig1.setRecommendedInflation(0F);
                GoalDecumulationAllocationRequest goalDecumulationAllocationRequest = new GoalDecumulationAllocationRequest();
                goalDecumulationAllocationRequest.setAllocationMethod(GoalDecumulationAllocationRequest.AllocationMethodEnum.CREATE);
                goalDecumulationAllocationRequest.setAllocationPriority(GoalDecumulationAllocationRequest.AllocationPriorityEnum.GOAL);
                OptConfig optConfig1 = new OptConfig();
                optConfig1.setTickers(Arrays.asList( "CVX",
                        "PFE",
                        "JNJ"));
                optConfig1.setMinAssets(3);
                WConfig wConfig1 = new WConfig();
                wConfig1.setWMinMajor(0F);
                wConfig1.setWMaxMajor(1F);
                wConfig1.setWMinMinor(0F);
                wConfig1.setWMaxMinor(1F);
                wConfig1.setCashAmount(0F);
                optConfig1.setWConfig(wConfig1);
                Map<String, Object> wAssetConfig1 = new HashMap<>();
                wAssetConfig1.put("US_Equities", 1);
                wAssetConfig1.put("Fixed_Income", 1);
                wAssetConfig1.put("Intl_Equities", 1);
                optConfig1.setWAssetConfig(wAssetConfig1);
                optConfig1.setSecTypes(Arrays.asList(
                        OptConfig.SecTypesEnum.MINOR, OptConfig.SecTypesEnum.MAJOR, OptConfig.SecTypesEnum.MINOR
                ));
                optConfig1.setStartDate(LocalDate.parse("2017-01-01"));
                optConfig1.setEndDate(LocalDate.parse("2018-12-31"));
                goalDecumulationAllocationRequest.setOptConfig(optConfig1);
                goalDecumulationAllocationRequest.setCurrInv(BigDecimal.valueOf(10000L));
                goalDecumulationAllocationRequest.setAHorizon(3);
                goalDecumulationAllocationRequest.setDHorizon(2);
                goalDecumulationAllocationRequest.setHorizonFrequency(GoalDecumulationAllocationRequest.HorizonFrequencyEnum.YEAR);
                GoalWithdrawalConfig withdrawalConfig = new GoalWithdrawalConfig();
                withdrawalConfig.setWithAmount(BigDecimal.valueOf(15000L));
                withdrawalConfig.setWithStartReference(GoalWithdrawalConfig.WithStartReferenceEnum.A_END);
                withdrawalConfig.setWithStartPeriod(0);
                withdrawalConfig.setWithEndReference(GoalWithdrawalConfig.WithEndReferenceEnum.D_END);
                withdrawalConfig.setWithEndPeriod(0);
                withdrawalConfig.setWithFrequency(GoalWithdrawalConfig.WithFrequencyEnum.YEAR);
                withdrawalConfig.setWithInflation(0F);
                goalDecumulationAllocationRequest.setWithdrawalConfig(Arrays.asList(withdrawalConfig));
                DecumulationGoalDepositConfig decumulationGoalDepositConfig = new DecumulationGoalDepositConfig();
                decumulationGoalDepositConfig.setDepStartReference(DecumulationGoalDepositConfig.DepStartReferenceEnum.A_START);
                decumulationGoalDepositConfig.setDepStartPeriod(0);
                decumulationGoalDepositConfig.setDepEndReference(DecumulationGoalDepositConfig.DepEndReferenceEnum.A_START);
                decumulationGoalDepositConfig.setDepEndPeriod(3);
                decumulationGoalDepositConfig.setDepAmount(BigDecimal.valueOf(2000));
                decumulationGoalDepositConfig.setDepFrequency(DecumulationGoalDepositConfig.DepFrequencyEnum.YEAR);
                decumulationGoalDepositConfig.setDepInflation(0F);
                goalDecumulationAllocationRequest.setDepositConfig(Arrays.asList(decumulationGoalDepositConfig));
                goalDecumulationAllocationRequest.setRecommendationConfig(recommendationConfig);
                goalDecumulationAllocationRequest.setRecommendType(GoalDecumulationAllocationRequest.RecommendTypeEnum.RECURRING);
                goalDecumulationAllocationRequest.setConfTgt(0.9F);
                goalDecumulationAllocationRequest.setN(1000);
                goalDecumulationAllocationRequest.setRemoveOutliers(Boolean.TRUE);
                goalDecumulationAllocationRequest.setThreshType(GoalDecumulationAllocationRequest.ThreshTypeEnum.PERC
                );
                goalDecumulationAllocationRequest.setThresh(BigDecimal.ZERO);
                goalDecumulationAllocationRequest.setWithdrawalTax(0F);
                goalDecumulationAllocationRequest.setTradingDaysPerYear(252);
                goalDecumulationAllocationRequest.setAdjustForCompounding(Boolean.FALSE);
                goalDecumulationAllocationRequest.setCompoundingRate(0F);
                goalDecumulationAllocationRequest.setCreateLog(Boolean.FALSE);
                Map<String, Object> goalDecumulationAllocationResponse = goalsApi.goalDecumulationAllocation(goalDecumulationAllocationRequest);
                System.out.println(goalDecumulationAllocationResponse);
api_instance = proton_api.GoalsApi(proton_api.ApiClient(configuration))
goal_config = proton_api.GoalConfig(goal_amount=25000, goal_inflation=0)
accumulation_goal_deposit_config = proton_api.AccumulationGoalDepositConfig(
    dep_amount=2000, dep_start_reference='a_start', dep_start_period=0, dep_end_reference='a_start',
    dep_end_period=3, dep_inflation=0
)
recommendation_config = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

recommendation_config1 = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

goal_decumulation_allocation_request = proton_api.GoalDecumulationAllocationRequest(
    allocation_method='create', allocation_priority='goal', opt_config=proton_api.OptConfig(
        tickers=["CVX",
                 "PFE",
                 "JNJ"], min_assets=3, w_config=proton_api.WConfig(
            w_min_major=0, w_max_major=1, w_min_minor=0, w_max_minor=1, cash_amount=0
        ), w_asset_config={
            "US_Equities": 1,
            "Fixed_Income": 1,
            "Intl_Equities": 1
        }, sec_types=['minor', 'major', 'major'], start_date="2017-01-01", end_date="2018-12-31"
    ), curr_inv=10000, a_horizon=3, d_horizon=2, horizon_frequency='year',
    withdrawal_config=[proton_api.GoalWithdrawalConfig(
        with_amount=15000, with_start_reference='a_end', with_start_period=0, with_end_reference='d_end',
        with_end_period=0, with_frequency='year', with_inflation=0
    )], deposit_config=[proton_api.DecumulationGoalDepositConfig(
        dep_start_reference='a_start', dep_start_period=0, dep_end_reference='a_end', dep_end_period=3, dep_amount=2000,
        dep_frequency='year', dep_inflation=0
    )], recommend_type='recurring',
    recommendation_config=recommendation_config, conf_tgt=0.09, n=1000, remove_outliers=True, thresh_type='perc',
    thresh=0, withdrawal_tax=0, trading_days_per_year=252, adjust_for_compounding=False, compounding_rate=0,
    create_log=False
)
try:
    # GoalApi - Goal Decumulation Allocation
    api_response = api_instance.goal_decumulation_allocation(goal_decumulation_allocation_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling GoalApi->goal_decumulation_allocation: %s\n" % e)
api_instance = ProtonApi::GoalsApi.new
# AccumulationGoalDepositConfig
accumulationDepositConfig = ProtonApi::AccumulationGoalDepositConfig.new
accumulationDepositConfig.dep_amount = 2000
accumulationDepositConfig.dep_start_reference = "a_start"
accumulationDepositConfig.dep_start_period = 0
accumulationDepositConfig.dep_end_reference = "a_start"
accumulationDepositConfig.dep_end_period = 3
accumulationDepositConfig.dep_frequency = "year"
accumulationDepositConfig.dep_inflation = 0
# Recommendation Config
recommendationConfig = ProtonApi::RecommendationConfig.new
recommendationConfig.recommend = true
recommendationConfig.inv_max = 1000
recommendationConfig.inv_min = 0
recommendationConfig.dep_min = 0
recommendationConfig.dep_max = 1000
recommendationConfig.horizon_min = 1
recommendationConfig.horizon_max = 10
recommendationConfig.recommended_inflation = 0
# Goal Config
goalConfig = ProtonApi::GoalConfig.new
goalConfig.goal_amount = 25000
goalConfig.goal_inflation = 0
# wConfig
wConfig = ProtonApi::WConfig1.new
wConfig.w_max_major = 1
wConfig.w_max_minor = 1
wConfig.w_min_major = 0
wConfig.w_min_minor = 0
wConfig.cash_amount = 0
# w_asset_config
w_asset_config = {
    "US_Equities" => 1,
    "Fixed_Income" => 1,
    "Intl_Equities" => 1
}
goalDecumulationAllocationRequest = ProtonApi::GoalDecumulationAllocationRequest.new
withdrawalConfig = ProtonApi::GoalWithdrawalConfig.new
withdrawalConfig.with_amount = 15000
withdrawalConfig.with_start_reference = "a_end"
withdrawalConfig.with_start_period = 0
withdrawalConfig.with_end_reference = "d_end"
withdrawalConfig.with_end_period = 0
withdrawalConfig.with_frequency = 'year'
withdrawalConfig.with_inflation = 0
decumulationGoalDepositConfig = ProtonApi::DecumulationGoalDepositConfig.new
decumulationGoalDepositConfig.dep_start_reference = "a_start"
decumulationGoalDepositConfig.dep_end_reference = "d_start"
decumulationGoalDepositConfig.dep_start_period = 0
decumulationGoalDepositConfig.dep_end_period = 0
decumulationGoalDepositConfig.dep_amount = 2000
decumulationGoalDepositConfig.dep_frequency = 'year'
decumulationGoalDepositConfig.dep_inflation = 0
begin
  goalDecumulationAllocationRequest.allocation_method = "create"
  goalDecumulationAllocationRequest.allocation_priority = "goal"
  goalDecumulationAllocationRequest.curr_inv = 10000
  goalDecumulationAllocationRequest.a_horizon = 3
  goalDecumulationAllocationRequest.a_horizon = 2
  goalDecumulationAllocationRequest.horizon_frequency = "year"
  optConfig = ProtonApi::OptConfig.new
  optConfig.w_asset_config = w_asset_config
  optConfig.min_assets = 3
  optConfig.sec_types = ["minor", "major", "minor"]
  optConfig.w_config = wConfig
  optConfig.start_date = "2017-01-01"
  optConfig.end_date = "2018-12-31"
  optConfig.tickers = ["CVX", "PFE", "JNJ"]
  goalDecumulationAllocationRequest.opt_config = optConfig
  goalDecumulationAllocationRequest.withdrawal_config = [withdrawalConfig]
  goalDecumulationAllocationRequest.deposit_config = [decumulationGoalDepositConfig]
  goalDecumulationAllocationRequest.recommendation_config = recommendationConfig
  goalDecumulationAllocationRequest.recommend_type = "recurring"
  goalDecumulationAllocationRequest.conf_tgt = 0.9
  goalDecumulationAllocationRequest.n = 1000
  goalDecumulationAllocationRequest.remove_outliers = true
  goalDecumulationAllocationRequest.thresh_type = "perc"
  goalDecumulationAllocationRequest.thresh = 0
  goalDecumulationAllocationRequest.withdrawal_tax = 0
  goalDecumulationAllocationRequest.trading_days_per_year = 252
  goalDecumulationAllocationRequest.risk_score = 77
  goalDecumulationAllocationRequest.adjust_for_compounding = false
  goalDecumulationAllocationRequest.compounding_rate = 0
  goalDecumulationAllocationRequest.use_proxy_data = false
  goalDecumulationAllocationRequest.market_data_source = "nucleus"
  goalDecumulationAllocationRequest.d_horizon = 2
  goalDecumulationAllocationRequest.create_log = false
  goalDecumulationAllocationResponse = api_instance.goal_decumulation_allocation(goalDecumulationAllocationRequest)
  p goalDecumulationAllocationResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling goal_decumulation_allocation #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\GoalsApi(
    new GuzzleHttp\Client(),
    $config
);
$goalDecumulationAllocationRequest = new com\hydrogen\proton\Model\GoalDecumulationAllocationRequest();
try {
    $goalDecumulationAllocationRequest->setallocationmethod("create");
    $goalDecumulationAllocationRequest->setallocationpriority("goal");
    $opt_config=new \com\hydrogen\proton\Model\OptConfig();
    $opt_config->setTickers(array("CVX","PFE","JNJ"));
    $opt_config->setMinAssets(3);
    $w_config = new \com\hydrogen\proton\Model\WConfig();
    $w_config->setWMinMajor(0);
    $w_config->setWMaxMajor(1);
    $w_config->setWMinMinor(0);
    $w_config->setWMaxMinor(1);
    $w_config->setCashAmount(0);
    $opt_config->setWConfig($w_config);

    $w_asset_config = new stdClass();
    $w_asset_config->US_Equities = 1;
    $w_asset_config->Fixed_Income =1;
    $w_asset_config->Intl_Equities=1;
    $opt_config->setWAssetConfig($w_asset_config);

    $opt_config->setSecTypes(array("major","major","minor"));

    $opt_config->setStartDate("2017-01-01");
    $opt_config->setEndDate("2018-12-01");
    $goalDecumulationAllocationRequest->setOptConfig($opt_config);


    $goalDecumulationAllocationRequest->setcurrinv(10000);
    $goalDecumulationAllocationRequest->setahorizon(3);
    $goalDecumulationAllocationRequest->setdhorizon(2);
    $goalDecumulationAllocationRequest->sethorizonfrequency("year");

    $withdrawalConfigDecumulation = new com\hydrogen\proton\Model\GoalWithdrawalConfig();
    $withdrawalConfigDecumulation->setWithStartReference("a_end");
    $withdrawalConfigDecumulation->setWithStartPeriod(0) ;
    $withdrawalConfigDecumulation->setWithEndReference("d_end");
    $withdrawalConfigDecumulation->setWithEndPeriod(3);
    $withdrawalConfigDecumulation->setWithAmount(15000) ;
    $withdrawalConfigDecumulation->setWithFrequency("year");
    $withdrawalConfigDecumulation->setWithInflation(0);
    $withdrawalConfigDecumulation->setWithAmount(15000);
    $goalDecumulationAllocationRequest->setWithDrawalConfig(array($withdrawalConfigDecumulation));

    $depositConfigDecumulation = new com\hydrogen\proton\Model\DecumulationGoalDepositConfig();
    $depositConfigDecumulation->setDepStartReference("a_start");
    $depositConfigDecumulation->setDepStartPeriod(0) ;
    $depositConfigDecumulation->setDepEndReference("a_start");
    $depositConfigDecumulation->setDepEndPeriod(3);
    $depositConfigDecumulation->setDepAmount(2000) ;
    $depositConfigDecumulation->setDepFrequency("year");
    $depositConfigDecumulation->setDepInflation(0);
    $goalDecumulationAllocationRequest->setDepositConfig(array($depositConfigDecumulation));

    $recommendationConfigDecumulation = new \com\hydrogen\proton\Model\RecommendationConfig();
    $recommendationConfigDecumulation->setRecommend(true);
    $recommendationConfigDecumulation->setInvMin(0);
    $recommendationConfigDecumulation->setInvMax(1000);
    $recommendationConfigDecumulation->setDepMax(1000);
    $recommendationConfigDecumulation->setDepMin(0);
    $recommendationConfigDecumulation->setHorizonMin(1);
    $recommendationConfigDecumulation->setHorizonMax(10);
    $recommendationConfigDecumulation->setRecommendedInflation(0);
    $goalDecumulationAllocationRequest->setRecommendationConfig(($recommendationConfigDecumulation));

    $goalDecumulationAllocationRequest->setRecommendType("recurring");
    $goalDecumulationAllocationRequest->setConfTgt(0.9);
    $goalDecumulationAllocationRequest->setN(1000);
    $goalDecumulationAllocationRequest->setRemoveOutliers(true);
    $goalDecumulationAllocationRequest->setThreshType("perc");
    $goalDecumulationAllocationRequest->setThresh(0);
    $goalDecumulationAllocationRequest->setWithdrawalTax(0);
    $goalDecumulationAllocationRequest->setTradingDaysPerYear(252);
    $goalDecumulationAllocationRequest->setRiskScore(77);
    $goalDecumulationAllocationRequest->setAdjustForCompounding(false);
    $goalDecumulationAllocationRequest->setCompoundingRate(0);
    $goalDecumulationAllocationRequest->setUseProxyData(false);
    $goalDecumulationAllocationRequest->setmarketdatasource("nucleus");
    $goalDecumulationAllocationRequest->setCreateLog(false);
    $result = $apiInstance->goalDecumulationAllocation($goalDecumulationAllocationRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling GoalsApi->goalDecumulationAllocation: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.GoalsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.GoalsApi();

var gdecumulationallocation = new HydrogenProtonApi.GoalDecumulationAllocationRequest();


gdecumulationallocation.allocation_method = "create";
gdecumulationallocation.allocation_priority = "goal";
gdecumulationallocation.allocations = ["406ec16e-ebae-4130-a6c0-1cacb72569a2",
    "740f6466-3300-4122-927d-4a691359fa32",
    "0a02058f-4046-48de-b3d2-aeefd6d4efac"];
gdecumulationallocation.risk_score = 77;
gdecumulationallocation.opt_config = {tickers: ["CVX", "PFE", "JNJ"],
w_asset_config: {"US_Equities": 1.0,
    "Fixed_Income": 1.0,
    "Intl_Equities": 1.0,},
min_assets: 3,
sec_types: ["minor", "major","minor"],
start_date: "2016-01-01",
end_date: "2019-01-01",
w_config: {
    w_min_major: 0.05,
    w_max_major: 1,
    w_min_minor: 0.05,
    w_max_minor: 0.1,
    cash_amount: 0.0
},
};


gdecumulationallocation.deposit_config = [{  depStartReference: "a_start",
    depStartPeriod: 0,
    depEndReference: "a_start",
    depEndPeriod: 3,
    depAmount: 2000,
    depFrequency: "year",
    depInflation: 0.0}];
gdecumulationallocation.withdrawal_config = [{
    with_amount: 15000,
    withStartReference: "a_end",
    withStartPeriod: 0,
    withEndReference: "d_end",
    withEndPeriod: 0,
    withFrequency: "year",
    withInflation: 0.0
}];
gdecumulationallocation.recommendation_config = {
    recommend: true,
    invMin: 0,
    invMax: 1000,
    depMin: 0,
    depMax: 1000,
    horizonMin: 1,
    horizonMax: 10,
    recommendedInflation: 0.0
};
gdecumulationallocation.trading_days_per_year = 252;
gdecumulationallocation.a_horizon = 3;
gdecumulationallocation.d_horizon = 2;
gdecumulationallocation.horizonFrequency = "year";
gdecumulationallocation.curr_inv = 10000;
gdecumulationallocation.recommendType = "recurring";
gdecumulationallocation.confTgt = 0.9;
gdecumulationallocation.create_log = false;
gdecumulationallocation.n = 1000;
gdecumulationallocation.remove_outliers = true;
gdecumulationallocation.threshType = "perc";
gdecumulationallocation.thresh = 0;
gdecumulationallocation.withdrawalTax = 0.0;
gdecumulationallocation.adjustForCompounding = false;
gdecumulationallocation.compoundingRate = 0.0;
apiInstance.goalDecumulationAllocation(gdecumulationallocation, callback)

ARGUMENTS

Parameter Description
allocation_method
string, required
The allocation universe source, may be either create or select. create constructs an allocation universe from a dynamically generated efficient frontier, based on opt_config. select derives an allocation universe from pre-defined allocations, as stipulated by allocations.
allocation_priority
string, required
The priority to consider when deriving the appropriate allocation, may be risk or goal. risk finds a portfolio that corresponds to an investor’s risk_score within the universe of potential portfolios. goal does not consider the investor’s risk_score, but rather allocates to a portfolio that best achieves the goal.
opt_config
map, conditional requirement
Portfolio optimization configuration, required if allocation_method = create. Information in opt_config refers to security data, which must be created in advance using the Nucleus endpoints POST /security and POST /security_price. opt_config includes the fields shown below.
      tickers
      array, required
A list of tickers to consider during the optimization process, referencing securities defined in the Nucleus API. We recommend using no more than 25 tickers in a single optimization. Pre-screening a securities universe prior to calling the service will result in faster execution times as well as more meaningful results.
      min_assets
      integer, required
The minimum number of portfolio assets, excluding the cash security (if applicable).
      w_config
      map, required
Weight constraints for security types, including w_min_major, w_max_major, w_min_minor, w_max_minor, and cash_amount, which stipulate lower and upper bounds for minor and major securities, as well as a constant weight for cash securities. Minimums are joined with zero to form a binary constraint. This means that the minimum weight of securities of each type may either be 0 or the stipulated minimum. For example, a w_min_major constraint of 5% indicates that if a major security is chosen during the optimization, its weight will be either 0% or >= 5%.
      w_asset_config
      map
Weight constraints for asset classes. Stipulates a maximum weight for the asset classes represented in tickers. If an asset class is represented in tickers but not found in w_asset_config, the weight for that asset class will not be constrained.
      sec_types
      array, required
A type for each security in tickers. Values may be major, minor, and cash. major securities are intended to be securities with more lenient weight thresholds. minor securities are intended to be securities with tighter weight thresholds. cash securities are constrained to a constant weight. major and minor designations interact with w_config to set distinct weight constraints for different kinds of securities. A maximum of one security may be labelled with the cash type.
      start_date
      date
Start date for historical prices in yyyy-mm-dd format.
      end_date
      date
End date for historical prices in yyyy-mm-dd format.
allocations
array(UUID)
List of allocation_ids in the Nucleus API to select from. As a pre-requisite, must have values for the performance and volatility arguments within the chosen allocation_id. Defaults to include all available allocations.
curr_inv
float, conditional requirement
The current amount invested toward the goal.
a_horizon
integer, conditional requirement
The accumulation horizon, with a frequency defined by horizon_frequency. For example, for a client that is looking to retire in 30 years, use a_horizon = 30. Must be greater than 0 if recommend_type is recurring or combo.
d_horizon
integer, conditional requirement
The decumulation horizon, with a frequency defined by horizon_frequency. For example, for a client that is looking to take withdrawals for 25 years during retirement, use d_horizon = 25. Must be greater than 0.
horizon_frequency
string, conditional requirement
The frequency in relation to the numbers defined in a_horizon and d_horizon, and at which to run the simulation. Must be one of the following: year, quarter, month, week, day.
withdrawal_config
array(map), conditional requirement
The withdrawals to occur during the goal’s decumulation phase. withdrawal_config is an array of maps, with each map containing the fields shown below.
      with_amount
      float, conditional requirement
The withdrawal amount, in today’s dollars.
      with_start_reference
      string
The reference for the starting point of the withdrawal. May be a_end or d_end, which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to a_end.
      with_start_period
      integer
The starting period for the withdrawal, relative to with_start_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency. Defaults to 0.
      with_end_reference
      string
The reference for the ending point of the withdrawal. May be a_end or d_end, which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to d_end.
      with_end_period
      integer
The ending period for the withdrawal, relative to with_end_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency. Defaults to 0.
      with_frequency
      string
The frequency of the withdrawal. Must be one of the following: year, quarter, month, week, day. Defaults to year.
      with_inflation
      float
The annualized inflation rate for the withdrawal. Defaults to 0.
deposit_config
array(map)
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below.
      dep_start_reference
      string
The reference for the starting point of the deposit. May be a_start, a_end, or d_end, which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_start.
      dep_start_period
      integer
The starting period for the deposit, relative to dep_start_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_end_reference
      string
The reference for the ending point of the deposit. May be a_start, a_end, or d_end, which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_end.
      dep_end_period
      integer
The ending period for the deposit, relative to dep_end_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_amount
      float
The deposit amount, in today’s dollars. Defaults to 0.
      dep_frequency
      string
The frequency of the deposit. Must be one of the following: year, quarter, month, week, day. Defaults to year.
      dep_inflation
      float
The annualized inflation rate for the deposit. Defaults to 0.
recommendation_config
map
Information to configure the goal recommendation engine, including the fields shown below.
      recommend
      boolean
If true, generate a recommended action to improve goal probability. Recommendations are only generated if a goal is off-track. Defaults to true.
      inv_min
      float
The lower bound for one-time deposit recommendations. Defaults to 0.
      inv_max
      float
The upper bound for one-time deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon.
      dep_min
      float
The lower bound for recurring deposit recommendations. Defaults to 0.
      dep_max
      float
The upper bound for recurring deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon divided by a_horizon.
      horizon_min
      integer
The minimum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 1.
      horizon_max
      integer
The maximum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 64.
      recommended_inflation
      float
The annualized inflation rate attributed to a recommended recurring deposit.
recommend_type
string
The type of recommended action. Value may be recurring, one-time, combo, or horizon. recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon.
conf_tgt
float
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90.
n
integer
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000.
remove_outliers
boolean
If true, remove outlying results. If true, outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true.
thresh_type
string
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc.
thresh
float
The goal deviation threshold value, corresponding to thresh_type. Defaults to 0.
withdrawal_tax
float
The tax rate to apply to all withdrawals. Defaults to 0.
trading_days_per_year
integer
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day. Defaults to 252.
risk_score
integer
The investor’s risk score from 0 to 100, where 0 indicates minimum risk appetite and 100 indicates maximum risk appetite.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.
market_data_source
string
Source of security price data to be used in the analysis. Value may be nucleus or integration. When value is nucleus, security price data is sourced from Nucleus Security Price. When value is integration, security price data is sourced from a configured Integration Market Data vendor. Defaults to nucleus.
client_id
UUID, conditional requirement
The ID of a Nucleus client used to derive one or more of the following: curr_inv, a_horizon, d_horizon, horizon_frequency, and withdrawal_config.with_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
goal_id
UUID, conditional requirement
The ID of a Nucleus goal used to derive one or more of the following: curr_inv, a_horizon, d_horizon, horizon_frequency, and withdrawal_config.with_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
create_log
boolean
If true, a record of this Proton request URL, request body, response body, and Nucleus UUID(s), where applicable, will be stored in Electron as an audit log, and the resulting audit_log_id will be returned in the Proton response. Defaults to false.

Example Response

{
    "current_status": {
        "on_track": false,
        "progress": 0.4545,
        "goal_probability": 0.8342,
        "goal_achievement_score": 93,
        "return_details": {
            "0": {
                "period_earnings": 0,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 0,
                "accumulation_cumulative_deposit": 0,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 10000
            },
            "1": {
                "period_earnings": 326.32,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 326.32,
                "accumulation_cumulative_deposit": 2000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 12326.32
            },
            "2": {
                "period_earnings": 1033.7,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 1360.02,
                "accumulation_cumulative_deposit": 4000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 15360.02
            },
            "3": {
                "period_earnings": 1245.48,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 2605.5,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 18605.5
            },
            "4": {
                "period_earnings": 1669.58,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 4275.09,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 11000,
                "ending_balance": 9275.09
            },
            "5": {
                "period_earnings": 0,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 9275.09,
                "cumulative_earnings": 4275.09,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 20275.09,
                "ending_balance": 0
            }
        },
        "accumulation_balance": 18605.5
    },
    "recommended_status": {
        "on_track": true,
        "progress": 0.4545,
        "goal_probability": 0.9065,
        "goal_achievement_score": 100,
        "action": [
            {
                "value": 218.75,
                "freq_unit": "year",
                "value_type": "recurring_deposit"
            }
        ],
        "return_details": {
            "0": {
                "period_earnings": 0,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 0,
                "accumulation_cumulative_deposit": 0,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 10000
            },
            "1": {
                "period_earnings": 355.11,
                "accumulation_period_deposit": 2218.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 355.11,
                "accumulation_cumulative_deposit": 2218.75,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 12573.86
            },
            "2": {
                "period_earnings": 1040.96,
                "accumulation_period_deposit": 2218.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 1396.07,
                "accumulation_cumulative_deposit": 4437.5,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 15833.57
            },
            "3": {
                "period_earnings": 1230.63,
                "accumulation_period_deposit": 2218.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 2626.7,
                "accumulation_cumulative_deposit": 6656.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 19282.95
            },
            "4": {
                "period_earnings": 1864.12,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 4490.82,
                "accumulation_cumulative_deposit": 6656.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 11000,
                "ending_balance": 10147.07
            },
            "5": {
                "period_earnings": 988.6,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 5479.43,
                "accumulation_cumulative_deposit": 6656.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 22000,
                "ending_balance": 135.68
            }
        },
        "accumulation_balance": 19282.95
    },
    "allocation": {
        "ret": 0.1177,
        "risk": 0.0665,
        "assets": [
            "AGG",
            "AMZN",
            "CMCSA",
            "GOOGL",
            "KHC",
            "XOM"
        ],
        "weights": [
            0.5,
            0.1,
            0.1,
            0.1,
            0.1,
            0.1
        ],
        "identifier": null
    }
}

RESPONSE

Field Description
current_status The current status of the goal.
      on_track If true, the goal is on track.
      progress The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon.
      goal_probability The probability of achieving the goal with the given portfolio.
      goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
      return_details Portfolio return information over the length of the horizon, broken down by period.
            period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
            accumulation_period_deposit The deposit made for this period in the accumulation phase.
            decumulation_period_deposit The deposit made for this period in the decumulation phase.
            period_withdrawal The withdrawal made for this period.
            cumulative_earnings The cumulative investment earnings made up to and including this period.
            accumulation_cumulative_deposit The cumulative deposits made up to and including this period for the accumulation phase.
            decumulation_cumulative_deposit The cumulative deposits made up to and including this period for the decumulation phase.
            cumulative_withdrawals The cumulative withdrawals made up to and including this period.
            ending_balance The ending balance, inclusive of earnings and contributions for the current period.
      accumulation_balance The projected balance at the end of the accumulation horizon.
recommended_status The goal status based on the provided recommendation.
      on_track If true, the goal is on track.
      progress The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon.
      goal_probability The probability of achieving the goal with the given portfolio.
      goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
      action The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits.
            value The value of the recommended action.
            freq_unit The frequency unit of value.
            value_type The type of recommendation being made.
      return_details Portfolio return information over the length of the horizon, broken down by period.
            period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
            accumulation_period_deposit The deposit made for this period in the accumulation phase.
            decumulation_period_deposit The deposit made for this period in the decumulation phase.
            period_withdrawal The withdrawal made for this period.
            cumulative_earnings The cumulative investment earnings made up to and including this period.
            accumulation_cumulative_deposit The cumulative deposits made up to and including this period for the accumulation phase.
            decumulation_cumulative_deposit The cumulative deposits made up to and including this period for the decumulation phase.
            cumulative_withdrawals The cumulative withdrawals made up to and including this period.
            ending_balance The ending balance, inclusive of earnings and contributions for the current period.
      accumulation_balance The projected balance at the end of the accumulation horizon.
allocation Information about the chosen portfolio, including risk and return.
      ret The portfolio annualized return.
      risk The portfolio annualized standard deviation.
      assets The securities in the created portfolio, returned if allocation_method = create.
      weights The weights for each of the securities in the created portfolio, returned if allocation_method = create.
      identifier The allocation’s id, returned if allocation_method = select.
audit_log_id The unique id of the audit log record created in Electron. Only returned when create_log = true.

NUCLEUS DATA DEPENDENCIES

Decumulation Goal Recommendation

This service is a recommendation engine that generates actions to increase the likelihood of achieving a decumulation goal, based on portfolio attributes and a target goal amount. Available actions include various types of cash inflows as well as goal horizon extension. The engine will attempt to find the minimal recommended action that satisfies a goal confidence target, subject to the given constraints.

HTTP REQUEST

POST /goal_decumulation/recommendation

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "p_ret": [0.09],
        "p_risk": [0.05],
        "trading_days_per_year": 252,
        "a_horizon": 3,
        "d_horizon": 2,
        "horizon_frequency": "year",
        "deposit_config": [
            {
                "dep_start_reference": "a_start",
                "dep_start_period": 0,
                "dep_end_reference": "a_start",
                "dep_end_period": 3,
                "dep_amount": 2000,
                "dep_frequency": "year",
                "dep_inflation": 0.0
            }
        ],
        "withdrawal_config": [
            {
                "with_amount": 11000,
                "with_start_reference": "a_end",
                "with_start_period": 0,
                "with_end_reference": "d_end",
                "with_end_period": 0,
                "with_frequency": "year",
                "with_inflation": 0.0
            }
        ],
        "recommendation_config": {
            "inv_min": 0,
            "inv_max": 1000,
            "dep_min": 0,
            "dep_max": 1000,
            "horizon_min": 1,
            "horizon_max": 10,
            "recommended_inflation": 0.0
        },
        "curr_inv": 10000,
        "recommend_type": "recurring",
        "conf_tgt": 0.9,
        "n": 1000,
        "remove_outliers": true,
        "thresh_type": "perc",
        "thresh": 0,
        "withdrawal_tax": 0.0,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0
    }' "https://api.hydrogenplatform.com/proton/v1/goal_decumulation/recommendation"
GoalsApi goalsApi = new GoalsApi();
GoalConfig goalConfig = new GoalConfig();
goalConfig.setGoalAmount(BigDecimal.valueOf(25000L));
goalConfig.setGoalInflation(0F);
AccumulationGoalDepositConfig goalDepositConfig = new AccumulationGoalDepositConfig();
goalDepositConfig.setDepAmount(BigDecimal.valueOf(2000));
goalDepositConfig.setDepStartReference(AccumulationGoalDepositConfig.DepStartReferenceEnum.START);
goalDepositConfig.setDepStartPeriod(0);
goalDepositConfig.setDepEndReference(AccumulationGoalDepositConfig.DepEndReferenceEnum.START);
goalDepositConfig.setDepEndPeriod(3);
goalDepositConfig.setDepInflation(0F);


RecommendationConfig recommendationConfig = new RecommendationConfig();
recommendationConfig.setRecommend(true);
recommendationConfig.setInvMin(BigDecimal.ZERO);
recommendationConfig.setInvMax(BigDecimal.valueOf(1000L));
recommendationConfig.setDepMin(BigDecimal.ZERO);
recommendationConfig.setDepMax(BigDecimal.valueOf(1000L));
recommendationConfig.setHorizonMin(1);
recommendationConfig.setHorizonMax(10);
recommendationConfig.setRecommendedInflation(0F);
RecommendationConfig1 recommendationConfig1 = new RecommendationConfig1();
recommendationConfig1.setInvMin(BigDecimal.ZERO);
recommendationConfig1.setInvMax(BigDecimal.valueOf(1000L));
recommendationConfig1.setDepMin(BigDecimal.ZERO);
recommendationConfig1.setDepMax(BigDecimal.valueOf(1000L));
recommendationConfig1.setHorizonMin(1);
recommendationConfig1.setHorizonMax(10);
recommendationConfig1.setRecommendedInflation(0F);
GoalDecumulationRecommendationRequest goalDecumulationRecommendationRequest = new GoalDecumulationRecommendationRequest();
goalDecumulationRecommendationRequest.setPRet(Arrays.asList(0.09F));
goalDecumulationRecommendationRequest.setPRisk(Arrays.asList(0.05F));
goalDecumulationRecommendationRequest.setCurrInv(BigDecimal.valueOf(10000));
goalDecumulationRecommendationRequest.setAHorizon(3);
goalDecumulationRecommendationRequest.setDHorizon(2);
goalDecumulationRecommendationRequest.setHorizonFrequency(GoalDecumulationRecommendationRequest.HorizonFrequencyEnum.YEAR);
goalDecumulationRecommendationRequest.setWithdrawalConfig(Arrays.asList(withdrawalConfig));
goalDecumulationRecommendationRequest.setDepositConfig(Arrays.asList(decumulationGoalDepositConfig));
goalDecumulationRecommendationRequest.setRecommendationConfig(recommendationConfig1);
goalDecumulationRecommendationRequest.setRecommendType(GoalDecumulationRecommendationRequest.RecommendTypeEnum.RECURRING);
goalDecumulationRecommendationRequest.setConfTgt(0.9F);
goalDecumulationRecommendationRequest.setN(1000);
goalDecumulationRecommendationRequest.setRemoveOutliers(Boolean.TRUE);
goalDecumulationRecommendationRequest.setThreshType(GoalDecumulationRecommendationRequest.ThreshTypeEnum.PERC
);
goalDecumulationRecommendationRequest.setThresh(BigDecimal.ZERO);
goalDecumulationRecommendationRequest.setWithdrawalTax(0F);
goalDecumulationRecommendationRequest.setTradingDaysPerYear(252);
goalDecumulationRecommendationRequest.setAdjustForCompounding(Boolean.FALSE);
goalDecumulationRecommendationRequest.setCompoundingRate(0F);
goalDecumulationRecommendationRequest.setCreateLog(Boolean.FALSE);
Map<String, Object> goalDecumulationRecommendationResponse = goalsApi.goalDecumulationRecommendation(goalDecumulationRecommendationRequest);
System.out.println(goalDecumulationRecommendationResponse);
api_instance = proton_api.GoalsApi(proton_api.ApiClient(configuration))
goal_config = proton_api.GoalConfig(goal_amount=25000, goal_inflation=0)
accumulation_goal_deposit_config = proton_api.AccumulationGoalDepositConfig(
    dep_amount=2000, dep_start_reference='a_start', dep_start_period=0, dep_end_reference='a_start',
    dep_end_period=3, dep_inflation=0
)
recommendation_config = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

recommendation_config1 = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

goal_decumulation_recommendation_request = proton_api.GoalDecumulationRecommendationRequest(
    p_risk=[0.05], curr_inv=10000, a_horizon=3, d_horizon=2, horizon_frequency='year', withdrawal_config=[
        proton_api.GoalWithdrawalConfig(
            with_amount=15000, with_start_reference='a_end', with_start_period=0, with_end_reference='d_end',
            with_end_period=0, with_frequency='year', with_inflation=0
        )
    ], deposit_config=[
        proton_api.DecumulationGoalDepositConfig(
            dep_start_reference='a_start', dep_start_period=0, dep_end_reference='a_end', dep_end_period=3,
            dep_amount=2000,
            dep_frequency='year', dep_inflation=0
        )
    ], recommendation_config=recommendation_config1, recommend_type='recurring', conf_tgt=0.9, n=1000,
    remove_outliers=True,
    thresh_type='perc', thresh=0, withdrawal_tax=0, trading_days_per_year=252, adjust_for_compounding=False,
    create_log=False, p_ret=[0.09]
)
try:
    # GoalApi - Goal Decumulation Recommendation
    api_response = api_instance.goal_decumulation_recommendation(goal_decumulation_recommendation_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling GoalApi->goal_decumulation_recommendation: %s\n" % e)
api_instance = ProtonApi::GoalsApi.new
# AccumulationGoalDepositConfig
accumulationDepositConfig = ProtonApi::AccumulationGoalDepositConfig.new
accumulationDepositConfig.dep_amount = 2000
accumulationDepositConfig.dep_start_reference = "a_start"
accumulationDepositConfig.dep_start_period = 0
accumulationDepositConfig.dep_end_reference = "a_start"
accumulationDepositConfig.dep_end_period = 3
accumulationDepositConfig.dep_frequency = "year"
accumulationDepositConfig.dep_inflation = 0
# Recommendation Config
recommendationConfig = ProtonApi::RecommendationConfig.new
recommendationConfig.recommend = true
recommendationConfig.inv_max = 1000
recommendationConfig.inv_min = 0
recommendationConfig.dep_min = 0
recommendationConfig.dep_max = 1000
recommendationConfig.horizon_min = 1
recommendationConfig.horizon_max = 10
recommendationConfig.recommended_inflation = 0
# Goal Config
goalConfig = ProtonApi::GoalConfig.new
goalConfig.goal_amount = 25000
goalConfig.goal_inflation = 0
# wConfig
wConfig = ProtonApi::WConfig1.new
wConfig.w_max_major = 1
wConfig.w_max_minor = 1
wConfig.w_min_major = 0
wConfig.w_min_minor = 0
wConfig.cash_amount = 0
# w_asset_config
w_asset_config = {
    "US_Equities" => 1,
    "Fixed_Income" => 1,
    "Intl_Equities" => 1
}
goalDecumulationRecommendationRequest = ProtonApi::GoalDecumulationRecommendationRequest.new

begin
  goalDecumulationRecommendationRequest.p_ret = [0.09]
  goalDecumulationRecommendationRequest.p_risk = [0.05]
  goalDecumulationRecommendationRequest.trading_days_per_year = 252
  goalDecumulationRecommendationRequest.a_horizon = 3
  goalDecumulationRecommendationRequest.d_horizon = 2
  goalDecumulationRecommendationRequest.horizon_frequency = "year"
  goalDecumulationRecommendationRequest.deposit_config = [decumulationGoalDepositConfig]
  goalDecumulationRecommendationRequest.withdrawal_config = [withdrawalConfig]
  goalDecumulationRecommendationRequest.recommendation_config = recommendationConfig
  goalDecumulationRecommendationRequest.curr_inv = 10000
  goalDecumulationRecommendationRequest.recommend_type = "recurring"
  goalDecumulationRecommendationRequest.conf_tgt = 0.9
  goalDecumulationRecommendationRequest.n = 1000
  goalDecumulationRecommendationRequest.remove_outliers = true
  goalDecumulationRecommendationRequest.thresh_type = 'perc'
  goalDecumulationRecommendationRequest.thresh = 0
  goalDecumulationRecommendationRequest.withdrawal_tax = 0.0
  goalDecumulationRecommendationRequest.adjust_for_compounding = false
  goalDecumulationRecommendationRequest.compounding_rate = 0.0
  goalDecumulationRecommendationRequest.create_log = false
  goalDecumulationRecommendationResponse = api_instance.goal_decumulation_recommendation(goalDecumulationRecommendationRequest)
  p goalDecumulationRecommendationResponse
rescue ProtonApi::ApiError => e
  puts "Exception when calling goal_decumulation_recommendation #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\GoalsApi(
    new GuzzleHttp\Client(),
    $config
);
$goalDecumulationRecommendationRequest = new com\hydrogen\proton\Model\GoalDecumulationRecommendationRequest();
try {$goalDecumulationRecommendationRequest->setPRet(array(0.09));
    $goalDecumulationRecommendationRequest->setPRisk(array(0.05));
    $goalDecumulationRecommendationRequest->setTradingDaysPerYear(252);
    $goalDecumulationRecommendationRequest->setAHorizon(3);
    $goalDecumulationRecommendationRequest->setDHorizon(2);
    $goalDecumulationRecommendationRequest->setHorizonFrequency("year");
    $depositConfigDecumRecomendation = new com\hydrogen\proton\Model\DecumulationGoalDepositConfig();
    $depositConfigDecumRecomendation->setDepStartReference("a_start");
    $depositConfigDecumRecomendation->setDepStartPeriod(0) ;
    $depositConfigDecumRecomendation->setDepEndReference("a_start");
    $depositConfigDecumRecomendation->setDepEndPeriod(3);
    $depositConfigDecumRecomendation->setDepAmount(15000) ;
    $depositConfigDecumRecomendation->setDepFrequency("year");
    $depositConfigDecumRecomendation->setDepInflation(0);
    $goalDecumulationRecommendationRequest->setDepositConfig([$depositConfigDecumRecomendation]);

    $withdrawalConfigDecumulation = new com\hydrogen\proton\Model\GoalWithdrawalConfig();
    $withdrawalConfigDecumulation->setWithStartReference("a_end");
    $withdrawalConfigDecumulation->setWithStartPeriod(0) ;
    $withdrawalConfigDecumulation->setWithEndReference("d_end");
    $withdrawalConfigDecumulation->setWithEndPeriod(3);
    $withdrawalConfigDecumulation->setWithAmount(11000) ;
    $withdrawalConfigDecumulation->setWithFrequency("year");
    $withdrawalConfigDecumulation->setWithInflation(0);
    $goalDecumulationRecommendationRequest->setWithdrawalConfig([$withdrawalConfigDecumulation]);

    $recommendationConfigDecumulation = new com\hydrogen\proton\Model\RecommendationConfig1();
    $recommendationConfigDecumulation->setInvMin(0);
    $recommendationConfigDecumulation->setInvMax(1000);
    $recommendationConfigDecumulation->setDepMax(1000);
    $recommendationConfigDecumulation->setDepMin(0);
    $recommendationConfigDecumulation->setHorizonMin(1);
    $recommendationConfigDecumulation->setHorizonMax(10);
    $recommendationConfigDecumulation->setRecommendedInflation(0);
    $goalDecumulationRecommendationRequest->setRecommendationConfig($recommendationConfigDecumulation);

    $goalDecumulationRecommendationRequest->setCurrInv(10000);
    $goalDecumulationRecommendationRequest->setRecommendType("recurring");
    $goalDecumulationRecommendationRequest->setConfTgt(0.9);
    $goalDecumulationRecommendationRequest->setN(1000);
    $goalDecumulationRecommendationRequest->setRemoveOutliers(true);
    $goalDecumulationRecommendationRequest->setThreshType("perc");
    $goalDecumulationRecommendationRequest->setThresh(0);
    $goalDecumulationRecommendationRequest->setWithdrawalTax(0.0);
    $goalDecumulationRecommendationRequest->setAdjustForCompounding(false);
    $goalDecumulationRecommendationRequest->setCompoundingRate(0.0);
    $goalDecumulationRecommendationRequest->setCreateLog(false);
    $result = $apiInstance->goalDecumulationRecommendation($goalDecumulationRecommendationRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling GoalsApi->goalDecumulationRecommendation: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.GoalsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.GoalsApi();
    var goalDecumulationRecommendationRequest = new HydrogenProtonApi. GoalDecumulationRecommendationRequest();
    goalDecumulationRecommendationRequest.p_ret = [0.09];
    goalDecumulationRecommendationRequest.p_risk = [0.05];
    goalDecumulationRecommendationRequest.trading_days_per_year = 252;
    goalDecumulationRecommendationRequest.a_horizon = 3;
    goalDecumulationRecommendationRequest.d_horizon = 2;
    goalDecumulationRecommendationRequest.horizon_frequency = "year";
    goalDecumulationRecommendationRequest.deposit_config =
        [{
            "dep_start_reference": "a_start",
            "dep_start_period": 0,
            "dep_end_reference": "a_start",
            "dep_end_period": 3,
            "dep_amount": 2000,
            "dep_frequency": "year",
            "dep_inflation": 0.0
        }];
    goalDecumulationRecommendationRequest.withdrawal_config=
        [{
            "with_amount": 11000,
            "with_start_reference": "a_end",
            "with_start_period": 0,
            "with_end_reference": "d_end",
            "with_end_period": 0,
            "with_frequency": "year",
            "with_inflation": 0.0
        }];

    goalDecumulationRecommendationRequest.recommendation_config =

        {
            "inv_min": 0,
            "inv_max": 1000,
            "dep_min": 0,
            "dep_max": 1000,
            "horizon_min": 1,
            "horizon_max": 10,
            "recommended_inflation": 0.0
        };
    goalDecumulationRecommendationRequest.curr_inv = 10000;
    goalDecumulationRecommendationRequest.recommend_type = "recurring";
    goalDecumulationRecommendationRequest.conf_tgt = 0.9;
    goalDecumulationRecommendationRequest.n = 1000;
    goalDecumulationRecommendationRequest.remove_outliers = "true";
    goalDecumulationRecommendationRequest.thresh_type = "perc";
    goalDecumulationRecommendationRequest.thresh = 0;
    goalDecumulationRecommendationRequest.withdrawal_tax = 0.0;
    goalDecumulationRecommendationRequest.adjust_for_compounding = "false";
    goalDecumulationRecommendationRequest.compounding_rate =0.0;
    api.goalDecumulationRecommendation(goalDecumulationRecommendationRequest, callback)

ARGUMENTS

Parameter Description
p_ret
array, required
The annual portfolio return per period. The length of the array must be less than or equal to the sum of a_horizon and d_horizon. If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods.
p_risk
array, required
The annual portfolio standard deviation per period. The length of the array must be less than or equal to the sum of a_horizon and d_horizon. If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_risk of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods.
curr_inv
float, conditional requirement
The current amount invested toward the goal.
a_horizon
integer, conditional requirement
The accumulation horizon, with a frequency defined by horizon_frequency. For example, for a client that is looking to retire in 30 years, use a_horizon = 30. Must be greater than 0 if recommend_type is recurring or combo.
d_horizon
integer, conditional requirement
The decumulation horizon, with a frequency defined by horizon_frequency. For example, for a client that is looking to take withdrawals for 25 years during retirement, use d_horizon = 25. Must be greater than 0.
horizon_frequency
string, conditional requirement
The frequency in relation to the numbers defined in a_horizon and d_horizon, and at which to run the simulation. Must be one of the following: year, quarter, month, week, day.
withdrawal_config
array(map), conditional requirement
The withdrawals to occur during the goal’s decumulation phase. withdrawal_config is an array of maps, with each map containing the fields shown below.
      with_amount
      float, conditional requirement
The withdrawal amount, in today’s dollars.
      with_start_reference
      string
The reference for the starting point of the withdrawal. May be a_end or d_end, which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to a_end.
      with_start_period
      integer
The starting period for the withdrawal, relative to with_start_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency. Defaults to 0.
      with_end_reference
      string
The reference for the ending point of the withdrawal. May be a_end or d_end, which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to d_end.
      with_end_period
      integer
The ending period for the withdrawal, relative to with_end_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency. Defaults to 0.
      with_frequency
      string
The frequency of the withdrawal. Must be one of the following: year, quarter, month, week, day. Defaults to year.
      with_inflation
      float
The annualized inflation rate for the withdrawal. Defaults to 0.
deposit_config
array(map)
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below.
      dep_start_reference
      string
The reference for the starting point of the deposit. May be a_start, a_end, or d_end, which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_start.
      dep_start_period
      integer
The starting period for the deposit, relative to dep_start_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_end_reference
      string
The reference for the ending point of the deposit. May be a_start, a_end, or d_end, which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_end.
      dep_end_period
      integer
The ending period for the deposit, relative to dep_end_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_amount
      float
The deposit amount, in today’s dollars. Defaults to 0.
      dep_frequency
      string
The frequency of the deposit. Must be one of the following: year, quarter, month, week, day. Defaults to year.
      dep_inflation
      float
The annualized inflation rate for the deposit. Defaults to 0.
recommendation_config
map
Information to configure the goal recommendation engine, including the fields shown below.
      inv_min
      float
The lower bound for one-time deposit recommendations. Defaults to 0.
      inv_max
      float
The upper bound for one-time deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon.
      dep_min
      float
The lower bound for recurring deposit recommendations. Defaults to 0.
      dep_max
      float
The upper bound for recurring deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon divided by a_horizon.
      horizon_min
      integer
The minimum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 1.
      horizon_max
      integer
The maximum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 64.
      recommended_inflation
      float
The annualized inflation rate attributed to a recommended recurring deposit.
recommend_type
string
The type of recommended action. Value may be recurring, one-time, combo, or horizon. recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon.
conf_tgt
float
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90.
n
integer
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000.
remove_outliers
boolean
If true, remove outlying results. If true, outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true.
thresh_type
string
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc.
thresh
float
The goal deviation threshold value, corresponding to thresh_type. Defaults to 0.
withdrawal_tax
float
The tax rate to apply to all withdrawals. Defaults to 0.
trading_days_per_year
integer
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day. Defaults to 252.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.
client_id
UUID, conditional requirement
The ID of a Nucleus client used to derive one or more of the following: curr_inv, a_horizon, d_horizon, horizon_frequency, and withdrawal_config.with_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
goal_id
UUID, conditional requirement
The ID of a Nucleus goal used to derive one or more of the following: curr_inv, a_horizon, d_horizon, horizon_frequency, and withdrawal_config.with_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
create_log
boolean
If true, a record of this Proton request URL, request body, response body, and Nucleus UUID(s), where applicable, will be stored in Electron as an audit log, and the resulting audit_log_id will be returned in the Proton response. Defaults to false.

Example Response

{
    "on_track": true,
    "progress": 0.4545,
    "goal_probability": 0.9127,
    "goal_achievement_score": 100,
    "action": [
        {
            "value": 625,
            "freq_unit": "year",
            "value_type": "recurring_deposit"
        }
    ],
    "return_details": {
        "0": {
            "period_earnings": 0,
            "accumulation_period_deposit": 0,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 0,
            "accumulation_cumulative_deposit": 0,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 10000
        },
        "1": {
            "period_earnings": 261.03,
            "accumulation_period_deposit": 2625,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 261.03,
            "accumulation_cumulative_deposit": 2625,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 12886.03
        },
        "2": {
            "period_earnings": 819.01,
            "accumulation_period_deposit": 2625,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 1080.04,
            "accumulation_cumulative_deposit": 5250,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 16330.04
        },
        "3": {
            "period_earnings": 1006.41,
            "accumulation_period_deposit": 2625,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 2086.45,
            "accumulation_cumulative_deposit": 7875,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 19961.45
        },
        "4": {
            "period_earnings": 1358.01,
            "accumulation_period_deposit": 0,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 11000,
            "cumulative_earnings": 3444.47,
            "accumulation_cumulative_deposit": 7875,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 11000,
            "ending_balance": 10319.47
        },
        "5": {
            "period_earnings": 832.18,
            "accumulation_period_deposit": 0,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 11000,
            "cumulative_earnings": 4276.65,
            "accumulation_cumulative_deposit": 7875,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 22000,
            "ending_balance": 151.65
        }
    },
    "accumulation_balance": 19961.45
}

RESPONSE

Field Description
on_track If true, the goal is on track.
progress The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon.
goal_probability The probability of achieving the goal with the given portfolio.
goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
action The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits.
      value The value of the recommended action.
      freq_unit The frequency unit of value.
      value_type The type of recommendation being made.
return_details Portfolio return information over the length of the horizon, broken down by period.
      period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
      accumulation_period_deposit The deposit made for this period in the accumulation phase.
      decumulation_period_deposit The deposit made for this period in the decumulation phase.
      period_withdrawal The withdrawal made for this period.
      cumulative_earnings The cumulative investment earnings made up to and including this period.
      accumulation_cumulative_deposit The cumulative deposits made up to and including this period for the accumulation phase.
      decumulation_cumulative_deposit The cumulative deposits made up to and including this period for the decumulation phase.
      cumulative_withdrawals The cumulative withdrawals made up to and including this period.
      ending_balance The ending balance, inclusive of earnings and contributions for the current period.
accumulation_balance The projected balance at the end of the accumulation horizon.
audit_log_id The unique id of the audit log record created in Electron. Only returned when create_log = true.

NUCLEUS DATA DEPENDENCIES

Decumulation Goal Status

This service analyzes the state of expected goal achievement for a decumulation goal, based on the current goal configuration and context. In addition to a raw indication of whether a goal is on or off track, the service provides other metrics for advanced analysis. This framework also has built-in support for a goal recommendation engine, which recommends actions that may be taken to increase the expected goal achievement probability if a goal is off track.

HTTP REQUEST

POST /goal_decumulation/status

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "p_ret": [0.09],
        "p_risk": [0.05],
        "trading_days_per_year": 252,
        "a_horizon": 3,
        "d_horizon": 2,
        "horizon_frequency": "year",
        "deposit_config": [
            {
                "dep_start_reference": "a_start",
                "dep_start_period": 0,
                "dep_end_reference": "a_start",
                "dep_end_period": 3,
                "dep_amount": 2000,
                "dep_frequency": "year",
                "dep_inflation": 0.0
            }
        ],
        "withdrawal_config": [
            {
                "with_amount": 11000,
                "with_start_reference": "a_end",
                "with_start_period": 0,
                "with_end_reference": "d_end",
                "with_end_period": 0,
                "with_frequency": "year",
                "with_inflation": 0.0
            }
        ],
        "recommendation_config": {
            "recommend": true,
            "inv_min": 0,
            "inv_max": 1000,
            "dep_min": 0,
            "dep_max": 1000,
            "horizon_min": 1,
            "horizon_max": 10,
            "recommended_inflation": 0.0
        },
        "curr_inv": 10000,
        "recommend_type": "recurring",
        "conf_tgt": 0.9,
        "n": 1000,
        "remove_outliers": true,
        "thresh_type": "perc",
        "thresh": 0,
        "withdrawal_tax": 0.0,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0
    }' "https://api.hydrogenplatform.com/proton/v1/goal_decumulation/status"
GoalsApi goalsApi = new GoalsApi();
GoalConfig goalConfig = new GoalConfig();
goalConfig.setGoalAmount(BigDecimal.valueOf(25000L));
goalConfig.setGoalInflation(0F);
AccumulationGoalDepositConfig goalDepositConfig = new AccumulationGoalDepositConfig();
goalDepositConfig.setDepAmount(BigDecimal.valueOf(2000));
goalDepositConfig.setDepStartReference(AccumulationGoalDepositConfig.DepStartReferenceEnum.START);
goalDepositConfig.setDepStartPeriod(0);
goalDepositConfig.setDepEndReference(AccumulationGoalDepositConfig.DepEndReferenceEnum.START);
goalDepositConfig.setDepEndPeriod(3);
goalDepositConfig.setDepInflation(0F);


RecommendationConfig recommendationConfig = new RecommendationConfig();
recommendationConfig.setRecommend(true);
recommendationConfig.setInvMin(BigDecimal.ZERO);
recommendationConfig.setInvMax(BigDecimal.valueOf(1000L));
recommendationConfig.setDepMin(BigDecimal.ZERO);
recommendationConfig.setDepMax(BigDecimal.valueOf(1000L));
recommendationConfig.setHorizonMin(1);
recommendationConfig.setHorizonMax(10);
recommendationConfig.setRecommendedInflation(0F);
RecommendationConfig1 recommendationConfig1 = new RecommendationConfig1();
recommendationConfig1.setInvMin(BigDecimal.ZERO);
recommendationConfig1.setInvMax(BigDecimal.valueOf(1000L));
recommendationConfig1.setDepMin(BigDecimal.ZERO);
recommendationConfig1.setDepMax(BigDecimal.valueOf(1000L));
recommendationConfig1.setHorizonMin(1);
recommendationConfig1.setHorizonMax(10);
recommendationConfig1.setRecommendedInflation(0F);
GoalDecumulationStatusRequest goalDecumulationStatusRequest = new GoalDecumulationStatusRequest();
goalDecumulationStatusRequest.setPRet(Arrays.asList(0.09F));
goalDecumulationStatusRequest.setPRisk(Arrays.asList(0.05F));
goalDecumulationStatusRequest.setCurrInv(BigDecimal.valueOf(1000));
goalDecumulationStatusRequest.setAHorizon(3);
goalDecumulationStatusRequest.setDHorizon(3);
goalDecumulationStatusRequest.setHorizonFrequency(GoalDecumulationStatusRequest.HorizonFrequencyEnum.YEAR);
goalDecumulationStatusRequest.setWithdrawalConfig(Arrays.asList(withdrawalConfig));
goalDecumulationStatusRequest.setDepositConfig(Arrays.asList(decumulationGoalDepositConfig));
goalDecumulationStatusRequest.setRecommendationConfig(recommendationConfig);
goalDecumulationStatusRequest.setRecommendType(GoalDecumulationStatusRequest.RecommendTypeEnum.RECURRING);
goalDecumulationStatusRequest.setConfTgt(0.9F);
goalDecumulationStatusRequest.setN(1000);
goalDecumulationStatusRequest.setRemoveOutliers(Boolean.TRUE);
goalDecumulationStatusRequest.setThreshType(GoalDecumulationStatusRequest.ThreshTypeEnum.PERC
);
goalDecumulationStatusRequest.setThresh(BigDecimal.ZERO);
goalDecumulationStatusRequest.setWithdrawalTax(0F);
goalDecumulationStatusRequest.setTradingDaysPerYear(252);
goalDecumulationStatusRequest.setAdjustForCompounding(Boolean.FALSE);
goalDecumulationStatusRequest.setCompoundingRate(0F);
goalDecumulationStatusRequest.setCreateLog(Boolean.FALSE);
Map<String , Object> goalDecumulationStatusResponse = goalsApi.goalDecumulationStatus(goalDecumulationStatusRequest);
System.out.println(goalDecumulationStatusResponse);
api_instance = proton_api.GoalsApi(proton_api.ApiClient(configuration))
goal_config = proton_api.GoalConfig(goal_amount=25000, goal_inflation=0)
accumulation_goal_deposit_config = proton_api.AccumulationGoalDepositConfig(
    dep_amount=2000, dep_start_reference='a_start', dep_start_period=0, dep_end_reference='a_start',
    dep_end_period=3, dep_inflation=0
)
recommendation_config = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

recommendation_config1 = proton_api.RecommendationConfig(
    recommend=True, inv_min=0, inv_max=1000, dep_min=0, dep_max=1000, horizon_min=1, horizon_max=10,
    recommended_inflation=0
)

goal_decumulation_status_request = proton_api.GoalDecumulationStatusRequest(
    p_ret=[0.09], p_risk=[0.05], curr_inv=1000, a_horizon=3, d_horizon=3, horizon_frequency='year',
    withdrawal_config=[proton_api.GoalWithdrawalConfig(
        with_amount=15000, with_start_reference='a_end', with_start_period=0, with_end_reference='d_end',
        with_end_period=0, with_frequency='year', with_inflation=0
    )], deposit_config=[
        proton_api.DecumulationGoalDepositConfig(
            dep_start_reference='a_start', dep_start_period=0, dep_end_reference='a_end', dep_end_period=3,
            dep_amount=2000,
            dep_frequency='year', dep_inflation=0
        )
    ], recommendation_config=recommendation_config, recommend_type='recurring', conf_tgt=0.9, n=1000,
    remove_outliers=True,
    thresh_type='perc', thresh=0, withdrawal_tax=0, trading_days_per_year=252, adjust_for_compounding=False,
    compounding_rate=0, create_log=False
)
try:
    # GoalApi - Goal Decumulation Status
    api_response = api_instance.goal_decumulation_status(goal_decumulation_status_request)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling GoalApi->goal_decumulation_status: %s\n" % e)
api_instance = ProtonApi::GoalsApi.new
# AccumulationGoalDepositConfig
accumulationDepositConfig = ProtonApi::AccumulationGoalDepositConfig.new
accumulationDepositConfig.dep_amount = 2000
accumulationDepositConfig.dep_start_reference = "a_start"
accumulationDepositConfig.dep_start_period = 0
accumulationDepositConfig.dep_end_reference = "a_start"
accumulationDepositConfig.dep_end_period = 3
accumulationDepositConfig.dep_frequency = "year"
accumulationDepositConfig.dep_inflation = 0
# Recommendation Config
recommendationConfig = ProtonApi::RecommendationConfig.new
recommendationConfig.recommend = true
recommendationConfig.inv_max = 1000
recommendationConfig.inv_min = 0
recommendationConfig.dep_min = 0
recommendationConfig.dep_max = 1000
recommendationConfig.horizon_min = 1
recommendationConfig.horizon_max = 10
recommendationConfig.recommended_inflation = 0
# Goal Config
goalConfig = ProtonApi::GoalConfig.new
goalConfig.goal_amount = 25000
goalConfig.goal_inflation = 0
# wConfig
wConfig = ProtonApi::WConfig1.new
wConfig.w_max_major = 1
wConfig.w_max_minor = 1
wConfig.w_min_major = 0
wConfig.w_min_minor = 0
wConfig.cash_amount = 0
# w_asset_config
w_asset_config = {
    "US_Equities" => 1,
    "Fixed_Income" => 1,
    "Intl_Equities" => 1
}
goalDecumulationStatusRequest = ProtonApi::GoalDecumulationStatusRequest.new
begin
  goalDecumulationStatusRequest.p_ret = [0.09]
  goalDecumulationStatusRequest.p_risk = [0.05]
  goalDecumulationStatusRequest.trading_days_per_year = 252
  goalDecumulationStatusRequest.a_horizon = 3
  goalDecumulationStatusRequest.d_horizon = 2
  goalDecumulationStatusRequest.horizon_frequency = "year"
  goalDecumulationStatusRequest.deposit_config = [decumulationGoalDepositConfig]
  goalDecumulationStatusRequest.withdrawal_config = [withdrawalConfig]
  goalDecumulationStatusRequest.recommendation_config = recommendationConfig
  goalDecumulationStatusRequest.curr_inv = 10000
  goalDecumulationStatusRequest.recommend_type = "recurring"
  goalDecumulationStatusRequest.conf_tgt = 0.9
  goalDecumulationStatusRequest.n = 1000
  goalDecumulationStatusRequest.remove_outliers = "true"
  goalDecumulationStatusRequest.thresh_type = "perc"
  goalDecumulationStatusRequest.thresh = 0
  goalDecumulationStatusRequest.withdrawal_tax = 0.0
  goalDecumulationStatusRequest.adjust_for_compounding = "false"
  goalDecumulationStatusRequest.compounding_rate = 0.0
  goalDecumulationStatusRequest.create_log = false
  goal_decumulation_status = api_instance.goal_decumulation_status(goalDecumulationStatusRequest)
  p goal_decumulation_status
rescue ProtonApi::ApiError => e
  puts "Exception when calling goal_decumulation_status #{e}"
end
$apiInstance = new com\hydrogen\proton\Api\GoalsApi(
    new GuzzleHttp\Client(),
    $config
);
$goalDecumulationStatusRequest = new com\hydrogen\proton\Model\GoalDecumulationStatusRequest();
try {

    $goalDecumulationStatusRequest->setPRet(array(0.09));
    $goalDecumulationStatusRequest->setPRisk(array(0.05));
    $goalDecumulationStatusRequest->setTradingDaysPerYear(252);
    $goalDecumulationStatusRequest->setAHorizon(3);
    $goalDecumulationStatusRequest->setDHorizon(3);
    $goalDecumulationStatusRequest->setHorizonFrequency("year");

    $depositConfigGoalDecumulationStatus = new com\hydrogen\proton\Model\DecumulationGoalDepositConfig();
    $depositConfigGoalDecumulationStatus->setDepStartReference("a_start");
    $depositConfigGoalDecumulationStatus->setDepStartPeriod(0) ;
    $depositConfigGoalDecumulationStatus->setDepEndReference("a_start");
    $depositConfigGoalDecumulationStatus->setDepEndPeriod(3);
    $depositConfigGoalDecumulationStatus->setDepAmount(2000) ;
    $depositConfigGoalDecumulationStatus->setDepFrequency("year");
    $depositConfigGoalDecumulationStatus->setDepInflation(0);
    $goalDecumulationStatusRequest->setDepositConfig(array($depositConfigGoalDecumulationStatus));

    $withdrawalGoalDecumulationStatusConfig = new com\hydrogen\proton\Model\GoalWithdrawalConfig();
    $withdrawalGoalDecumulationStatusConfig->setWithStartReference("a_end");
    $withdrawalGoalDecumulationStatusConfig->setWithStartPeriod(0) ;
    $withdrawalGoalDecumulationStatusConfig->setWithEndReference("d_end");
    $withdrawalGoalDecumulationStatusConfig->setWithEndPeriod(3);
    $withdrawalGoalDecumulationStatusConfig->setWithAmount(11000) ;
    $withdrawalGoalDecumulationStatusConfig->setWithFrequency("year");
    $withdrawalGoalDecumulationStatusConfig->setWithInflation(0);
    $goalDecumulationStatusRequest->setWithdrawalConfig(array($withdrawalGoalDecumulationStatusConfig));

    $recommendationGoalDecumulationStatusConfig = new com\hydrogen\proton\Model\RecommendationConfig();
    $recommendationGoalDecumulationStatusConfig->setInvMin(0);
    $recommendationGoalDecumulationStatusConfig->setInvMax(1000);
    $recommendationGoalDecumulationStatusConfig->setDepMax(1000);
    $recommendationGoalDecumulationStatusConfig->setDepMin(0);
    $recommendationGoalDecumulationStatusConfig->setHorizonMin(1);
    $recommendationGoalDecumulationStatusConfig->setHorizonMax(10);
    $recommendationGoalDecumulationStatusConfig->setRecommendedInflation(0);
    $goalDecumulationStatusRequest->setRecommendationConfig(($recommendationGoalDecumulationStatusConfig));

    $goalDecumulationStatusRequest->setCurrInv(10000);
    $goalDecumulationStatusRequest->setRecommendType("recurring");
    $goalDecumulationStatusRequest->setConfTgt(0.9);
    $goalDecumulationStatusRequest->setN(1000);
    $goalDecumulationStatusRequest->setRemoveOutliers(true);
    $goalDecumulationStatusRequest->setThreshType("perc");
    $goalDecumulationStatusRequest->setThresh(0);
    $goalDecumulationStatusRequest->setWithdrawalTax(0.0);
    $goalDecumulationStatusRequest->setAdjustForCompounding(false);
    $goalDecumulationStatusRequest->setCompoundingRate(0.0);
    $goalDecumulationStatusRequest->setCreateLog(false);

    $result = $apiInstance->goalDecumulationStatus($goalDecumulationStatusRequest);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling GoalsApi->goalDecumulationStatus: ', $e->getMessage(), PHP_EOL;
}
var apiInstance = new HydrogenProtonApi.GoalsApi();
var callback = function(error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' +JSON.stringify(data, null, '\t') + '\n');
    }
};
var api = new HydrogenProtonApi.GoalsApi();
    var goalDecumulationStatusRequest = new HydrogenProtonApi. GoalDecumulationStatusRequest();
    goalDecumulationStatusRequest.p_ret = [0.09];
    goalDecumulationStatusRequest.p_risk = [0.05];
    goalDecumulationStatusRequest.trading_days_per_year = 252;
    goalDecumulationStatusRequest.a_horizon = 3;
    goalDecumulationStatusRequest.d_horizon = 3;
    goalDecumulationStatusRequest.horizon_frequency = "year";
    goalDecumulationStatusRequest.deposit_config =
        [{
            "dep_start_reference": "a_start",
            "dep_start_period": 0,
            "dep_end_reference": "a_start",
            "dep_end_period": 3,
            "dep_amount": 2000,
            "dep_frequency": "year",
            "dep_inflation": 0.0
        }];
    goalDecumulationStatusRequest.withdrawal_config =
        [{
            "with_amount": 11000,
            "with_start_reference": "a_end",
            "with_start_period": 0,
            "with_end_reference": "d_end",
            "with_end_period": 0,
            "with_frequency": "year",
            "with_inflation": 0.0
        }];

    goalDecumulationStatusRequest.recommendation_config = {
        "recommend": true,
        "inv_min": 0,
        "inv_max": 1000,
        "dep_min": 0,
        "dep_max": 1000,
        "horizon_min": 1,
        "horizon_max": 10,
        "recommended_inflation": 0.0
    };
    goalDecumulationStatusRequest.curr_inv = 10000;
    goalDecumulationStatusRequest.recommend_type = "recurring";
    goalDecumulationStatusRequest.conf_tgt = 0.9;
    goalDecumulationStatusRequest.n = 1000;
    goalDecumulationStatusRequest.remove_outliers = "true";
    goalDecumulationStatusRequest.thresh_type = "perc";
    goalDecumulationStatusRequest.thresh = 0;
    goalDecumulationStatusRequest.withdrawal_tax = 0.0;
    goalDecumulationStatusRequest.adjust_for_compounding = "false";
    goalDecumulationStatusRequest.compounding_rate =0.0;
    goalDecumulationStatusRequest.createLog = false;
    api.goalDecumulationStatus(goalDecumulationStatusRequest, callback)

ARGUMENTS

Parameter Description
p_ret
array, required
The annual portfolio return per period. The length of the array must be less than or equal to the sum of a_horizon and d_horizon. If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods.
p_risk
array, required
The annual portfolio standard deviation per period. The length of the array must be less than or equal to the sum of a_horizon and d_horizon. If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_risk of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods.
curr_inv
float, conditional requirement
The current amount invested toward the goal.
a_horizon
integer, conditional requirement
The accumulation horizon, with a frequency defined by horizon_frequency. For example, for a client that is looking to retire in 30 years, use a_horizon = 30. Must be greater than 0 if recommend_type is recurring or combo.
d_horizon
integer, conditional requirement
The decumulation horizon, with a frequency defined by horizon_frequency. For example, for a client that is looking to take withdrawals for 25 years during retirement, use d_horizon = 25. Must be greater than 0.
horizon_frequency
string, conditional requirement
The frequency in relation to the numbers defined in a_horizon and d_horizon, and at which to run the simulation. Must be one of the following: year, quarter, month, week, day.
withdrawal_config
array(map), conditional requirement
The withdrawals to occur during the goal’s decumulation phase. withdrawal_config is an array of maps, with each map containing the fields shown below.
      with_amount
      float, conditional requirement
The withdrawal amount, in today’s dollars.
      with_start_reference
      string
The reference for the starting point of the withdrawal. May be a_end or d_end, which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to a_end.
      with_start_period
      integer
The starting period for the withdrawal, relative to with_start_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency. Defaults to 0.
      with_end_reference
      string
The reference for the ending point of the withdrawal. May be a_end or d_end, which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to d_end.
      with_end_period
      integer
The ending period for the withdrawal, relative to with_end_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency. Defaults to 0.
      with_frequency
      string
The frequency of the withdrawal. Must be one of the following: year, quarter, month, week, day. Defaults to year.
      with_inflation
      float
The annualized inflation rate for the withdrawal. Defaults to 0.
deposit_config
array(map)
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below.
      dep_start_reference
      string
The reference for the starting point of the deposit. May be a_start, a_end, or d_end, which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_start.
      dep_start_period
      integer
The starting period for the deposit, relative to dep_start_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_end_reference
      string
The reference for the ending point of the deposit. May be a_start, a_end, or d_end, which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_end.
      dep_end_period
      integer
The ending period for the deposit, relative to dep_end_reference. A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency. Defaults to 0.
      dep_amount
      float
The deposit amount, in today’s dollars. Defaults to 0.
      dep_frequency
      string
The frequency of the deposit. Must be one of the following: year, quarter, month, week, day. Defaults to year.
      dep_inflation
      float
The annualized inflation rate for the deposit. Defaults to 0.
recommendation_config
map
Information to configure the goal recommendation engine, including the fields shown below.
      recommend
      boolean
If true, generate a recommended action to improve goal probability. Recommendations are only generated if a goal is off-track. Defaults to true.
      inv_min
      float
The lower bound for one-time deposit recommendations. Defaults to 0.
      inv_max
      float
The upper bound for one-time deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon.
      dep_min
      float
The lower bound for recurring deposit recommendations. Defaults to 0.
      dep_max
      float
The upper bound for recurring deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon divided by a_horizon.
      horizon_min
      integer
The minimum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 1.
      horizon_max
      integer
The maximum number of periods (defined by horizon_frequency) that the accumulation horizon may be extended when recommend_type = horizon. Defaults to 64.
      recommended_inflation
      float
The annualized inflation rate attributed to a recommended recurring deposit.
recommend_type
string
The type of recommended action. Value may be recurring, one-time, combo, or horizon. recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon.
conf_tgt
float
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90.
n
integer
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000.
remove_outliers
boolean
If true, remove outlying results. If true, outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true.
thresh_type
string
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc.
thresh
float
The goal deviation threshold value, corresponding to thresh_type. Defaults to 0.
withdrawal_tax
float
The tax rate to apply to all withdrawals. Defaults to 0.
trading_days_per_year
integer
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day. Defaults to 252.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency, as deposits are conformed to horizon_frequency during the analysis. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.
client_id
UUID, conditional requirement
The ID of a Nucleus client used to derive one or more of the following: curr_inv, a_horizon, d_horizon, horizon_frequency, and withdrawal_config.with_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
goal_id
UUID, conditional requirement
The ID of a Nucleus goal used to derive one or more of the following: curr_inv, a_horizon, d_horizon, horizon_frequency, and withdrawal_config.with_amount. If one or more of these required parameters are not provided, both client_id and goal_id are required.
create_log
boolean
If true, a record of this Proton request URL, request body, response body, and Nucleus UUID(s), where applicable, will be stored in Electron as an audit log, and the resulting audit_log_id will be returned in the Proton response. Defaults to false.

Example Response

{
    "current_status": {
        "on_track": false,
        "progress": 0.4545,
        "goal_probability": 0.5298,
        "goal_achievement_score": 59,
        "return_details": {
            "0": {
                "period_earnings": 0,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 0,
                "accumulation_cumulative_deposit": 0,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 10000
            },
            "1": {
                "period_earnings": 302.11,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 302.11,
                "accumulation_cumulative_deposit": 2000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 12302.11
            },
            "2": {
                "period_earnings": 722.99,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 1025.1,
                "accumulation_cumulative_deposit": 4000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 15025.1
            },
            "3": {
                "period_earnings": 971.45,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 1996.55,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 17996.55
            },
            "4": {
                "period_earnings": 1275.95,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 3272.5,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 11000,
                "ending_balance": 8272.5
            },
            "5": {
                "period_earnings": 0,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 8272.5,
                "cumulative_earnings": 3272.5,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 19272.5,
                "ending_balance": 0
            }
        },
        "accumulation_balance": 17996.55
    },
    "recommended_status": {
        "on_track": true,
        "progress": 0.4545,
        "goal_probability": 0.9043,
        "goal_achievement_score": 100,
        "action": [
            {
                "value": 593.75,
                "freq_unit": "year",
                "value_type": "recurring_deposit"
            }
        ],
        "return_details": {
            "0": {
                "period_earnings": 0,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 0,
                "accumulation_cumulative_deposit": 0,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 10000
            },
            "1": {
                "period_earnings": 280.94,
                "accumulation_period_deposit": 2593.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 280.94,
                "accumulation_cumulative_deposit": 2593.75,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 12874.69
            },
            "2": {
                "period_earnings": 700.92,
                "accumulation_period_deposit": 2593.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 981.86,
                "accumulation_cumulative_deposit": 5187.5,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 16169.36
            },
            "3": {
                "period_earnings": 1125.06,
                "accumulation_period_deposit": 2593.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 2106.92,
                "accumulation_cumulative_deposit": 7781.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 19888.17
            },
            "4": {
                "period_earnings": 1284.08,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 3391,
                "accumulation_cumulative_deposit": 7781.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 11000,
                "ending_balance": 10172.25
            },
            "5": {
                "period_earnings": 888.86,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 4279.86,
                "accumulation_cumulative_deposit": 7781.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 22000,
                "ending_balance": 61.11
            }
        },
        "accumulation_balance": 19888.17
    }
}

RESPONSE

Field Description
current_status The current status of the goal.
      on_track If true, the goal is on track.
      progress The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon.
      goal_probability The probability of achieving the goal with the given portfolio.
      goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
      return_details Portfolio return information over the length of the horizon, broken down by period.
            period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
            accumulation_period_deposit The deposit made for this period in the accumulation phase.
            decumulation_period_deposit The deposit made for this period in the decumulation phase.
            period_withdrawal The withdrawal made for this period.
            cumulative_earnings The cumulative investment earnings made up to and including this period.
            accumulation_cumulative_deposit The cumulative deposits made up to and including this period for the accumulation phase.
            decumulation_cumulative_deposit The cumulative deposits made up to and including this period for the decumulation phase.
            cumulative_withdrawals The cumulative withdrawals made up to and including this period.
            ending_balance The ending balance, inclusive of earnings and contributions for the current period.
      accumulation_balance The projected balance at the end of the accumulation horizon.
recommended_status The goal status based on the provided recommendation.
      on_track If true, the goal is on track.
      progress The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon.
      goal_probability The probability of achieving the goal with the given portfolio.
      goal_achievement_score A ratio of goal_probability to the conf_tgt on a scale from 0 to 100.
      action The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits.
            value The value of the recommended action.
            freq_unit The frequency unit of value.
            value_type The type of recommendation being made.
      return_details Portfolio return information over the length of the horizon, broken down by period.
            period_earnings The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made.
            accumulation_period_deposit The deposit made for this period in the accumulation phase.
            decumulation_period_deposit The deposit made for this period in the decumulation phase.
            period_withdrawal The withdrawal made for this period.
            cumulative_earnings The cumulative investment earnings made up to and including this period.
            accumulation_cumulative_deposit The cumulative deposits made up to and including this period for the accumulation phase.
            decumulation_cumulative_deposit The cumulative deposits made up to and including this period for the decumulation phase.
            cumulative_withdrawals The cumulative withdrawals made up to and including this period.
            ending_balance The ending balance, inclusive of earnings and contributions for the current period.
      accumulation_balance The projected balance at the end of the accumulation horizon.
audit_log_id The unique id of the audit log record created in Electron. Only returned when create_log = true.

NUCLEUS DATA DEPENDENCIES