Variables

A Variable is a named parameter that powers a piece of advice. Variables can be passed in as input or produced by the Rules Engine as the result of a formula, rule, or calculation.

Every API response includes a variables[] array. A single Variable looks like this:

{
  "dataType": "Freetext",
  "format": null,
  "id": "qT7UxR1ii",
  "isConstant": false,
  "isToggleable": false,
  "isSystem": false,
  "name": "Account_Type",
  "nameAlt": "Account Type",
  "type": "VARIABLE",
  "value": "Roth IRA",
  "valueDefault": null
}

Filtering Variables in the response

The variables[] array is trimmed by default: Variables with a null value, System Variables, and Constant Variables are all dropped. Send the filter parameter only when you want something other than that.

Combine values with commas to stack them. The default written out in full is:

?filter=variables,variables:!system,variables:!constant

🚧

Omitting filter used to return everything

An Advice API request that sent no filter previously received every Variable untrimmed. It now applies the default above. Send filter=all to keep the old response.

Each value also works on its own, and a modifier implies the base filter it modifies — filter=variables:!system drops null-valued Variables as well as System Variables.

A filter that is not a string or an array of strings — ?filter[foo]=bar, for instance — returns HTTP 400.

🚧

Not the same as Sparse Fieldsets

Variable filters trim entries from the variables[] array. Sparse Fieldsets trim properties off each entry. The two are independent and can be combined.

Variable properties

id

A unique identifier for the Variable.

dataType

The data type stored in the Variable. Possible values:

• Array
• Boolean
• Date
• Freetext
• Number
• Percent (alias for Number with a percent format)
• Radio

name

The canonical name of the Variable. Names always match /(^[a-zA-Z0-9][a-zA-Z0-9_?]*$)/ — alphanumerics, underscores, and question marks only.

nameAlt

A friendlier label for the Variable. Often unused.

value

The current value. A null here means the underlying question has not been answered yet.

valueDefault

A Taffrail-defined default for common scenarios — for example, 67 for Retirement_Age.

format

A format string the renderer uses to display the value. Most commonly used for Number, Percent, and Date. The API also returns valueFormatted with the format already applied.

{
  "format": "0[.]0",
  "value": 1.23,
  "valueFormatted": "1.2"
}

For all Variable types except Array, format is a string. For Array types, format is itself an array, with each entry matching the index of the corresponding value entry:

{
  "type": "Array",
  "value": [1, 2, 3],
  "format": [null, null, "0.0%"],
  "valueFormatted": [1, 2, "3.0%"]
}

See Formats for the full format string reference.

isToggleable

Only Boolean Variables can be toggleable. When true, the Backlink should render as a switch- or toggle-style control rather than a chip.

isConstant

true for Variables whose values are fixed reference data — IRS limits, regulatory thresholds, and similar — rather than user inputs. Use this to filter constants out of the UI.

isSystem

true for Variables used internally by the Rules Engine. System Variables are not meant for display, and are dropped from the response by default. Pass filter=all to include them.