Annuity Module - Request

The fields of the Data object supported by the Annuity module request are defined in alphabetical order below:

🟥 Data

The Data object encapsulates the request data for a given module, and must always be provided.

Fields: 🔹Balance, 🔹Calculate, 🔹Income, 🔸Rate, 🔹Term

Objects: 🟦 Format

🔹 Data.Balance

The beginning balance is the amount which is present in the retirment account when the annuity starts. Interest will accrue monthly on this amount, and the income stream is taken from this balance during the term of the annuity. If you are computing the beginning balance (e.g. "Calculate" : "Balance"), then this field may be omitted.

🔹 Data.Calculate

This field informs the SCE which of the three basic variables involved in an annuity calculation is to be calculated (e.g. Balance, Income, or Term).

In the sample above, the calculation type being requested is Income (the monthly income amount). Thus, the Balance, and Term fields are included in the request, whereas the Income field is omitted.

🔹 Data.Income

The value of this field specifies the desired monthly income amount. If you are computing the monthly income amount (e.g. "Calculate" : "Income"), then you may omit this field from the request.

🔸 Data.Rate

This field dictates the rate at which interest accrues throughout the term of the annuity.

🔹 Data.Term

This field specifies the number of months in the term of the annuity. This corresponds to the length of the monthly income stream which is disbursed from the beginning balance. If you are computing the number of months of income (e.g. "Calculate" : "Term"), then this field may be omitted.

🟦 Data.Format

The Format object is one of the first objects parsed from a request, as various fields affect how date and numeric fields are parsed and validated.

Fields: 🔹CurrencyDecimals, 🔹DateFormat, 🔹DateSeparator, 🔹DecimalSeparator, 🔹StrictDP, 🔹ThousandSeparator

Objects: None

🔹 Data.Format.CurrencyDecimals

When displaying and parsing Currency fields, this field determines the maximum number of decimal places allowed after the DecimalSeparator. If this field is not included, the default value [Country](#data-the default value is 2.

🔹 Data.Format.DateFormat

When displaying and parsing Date fields, this field determines the expected format for all Date fields. The following DateFormat options are allowed:

• YMD - All dates should be formated as YYYY-MM-DD.
• MDY - All dates should be formated as MM-DD-YYYY.
• DMY - All dates should be formated as DD-MM-YYYY.

Note that the character which separates the individual month, day, and year portions of the date is configurable via the DateSeparator field.

🔹 Data.Format.DateSeparator

When displaying and parsing Date fields, this field determines the character used to separate the individual month, day, and year portions of a date field.

🔹 Data.Format.DecimalSeparator

When displaying and parsing Currency, Percentage, or Floating numeric fields, this field determines the character used to separate the fractional part from the whole.

🔹 Data.Format.StrictDP

If the value of this field is true, then the SCE will strictly verify the number of decimal places allowed for currency input values. Thus, if the calling application sends in a request with a currency amount of 1000.005, the SCE will return an error code.

If the value of this field is set to false, then currency values sent in with an invalid number of decimal places will be rounded to the correct number of decimal places by the SCE (using five/four rounding), and a warning message with this information will be returned with the response.

🔹 Data.Format.ThousandSeparator

When displaying numeric fields, this field determines the character used to separate the thousands places from the hundreds. When parsing a numeric request field, if a thousand separator is specified in the request, then the SCE will now remove all occurrences of the specified thousand separator from the numeric field string before attempting to convert it to a number.