Retirement Annuities - Request

Please see the Legend to understand the conventions used to document each element and attribute. Note that for requests, the XML elements are documented in alphabetical order by parent element.

🟥 <inANNUITY>

Attributes: 🔹CalcType

This is the root element of the request, and is required. This contains child elements which specify the particulars of the requested annuity calculation, as well as calculation results. The following attributes of the <inANNUITY> element are defined:

🔹 CalcType

The CalcType attribute informs the SCE which of the three basic variables involved in the annuity is to be computed. The element corresponding to the variable being being solved for does not need to be present in the request (and if present, the value of the element will be ignored).

🟦 <BeginBalance>

The beginning balance is the amount which is present in the retirement 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. CalcType= "getBeginBalance"), then you may omit this element from the request.

Attributes: None

🟦 <Format>

The <Format> element is one of the first elements parsed from a request, as the attributes of this empty element affect how date and numeric values are parsed and validated.

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

🔹 CurrencyDecimals

When displaying and parsing Currency values, the value of this attribute determines the maximum number of decimal places allowed after the DecimalSeparator.

🔹 DateFormat

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

• YMD - All dates should be formatted as YYYY-MM-DD.
• MDY - All dates should be formatted as MM-DD-YYYY.
• DMY - All dates should be formatted 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 attribute.

🔹 DateSeparator

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

🔹 DecimalSeparator

When displaying and parsing Currency or Decimal numeric values, this attribute determines the character used to separate the fractional part from the whole.

🔹 StrictDP

If the value of this attribute 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 attribute is 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.

🔹 ThousandSeparator

When displaying numeric values, this attribute determines the character used to separate the thousands places from the hundreds. Note that when parsing numeric values, the value of this attribute is ignored.

🟥 <IntRate>

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

Attributes: None

🟦 <MonthlyIncome>

This element specifies the desired monthly income amount. If you are computing the monthly income amount (e.g. CalcType= "getMonthlyIncome"), then you may omit this element from the request.

Attributes: None

🟦 <MonthsOfIncome>

This element 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. CalcType= "getMonthsOfIncome"), then you may omit this element from the request.

Attributes: None