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 default response often includes more Variables than a given client needs. The filter parameter trims the variables[] array. Combine values with commas:

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

The example above drops Variables with a null value, System Variables, and Constant Variables. Each value can also be used on its own:

🚧

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. Pass filter=variables:!system to drop them from the response.