Advice Content Types

Use an Accept header to request a specific content format.

Our RESTful API understands and communicates in JSON. Consumers must send the Accept header with the desired and appropriate MIME type.

๐Ÿ“˜

Advice Content Formats

The API will always return JSON, but the Advice content contained within can be any of the following:

  • Plain text
  • Plain text with AttributedString definitions
  • HTML
  • HTML with no hyperlinks
  • Markdown (coming in a future release)

Since the API always returns JSON, the default Content-Type is application/json. In the default configuration, plain text will be the format for Advice content fields (which include question, explanation, headline, etc.).

To change the format of the Advice content within the API, use a custom Accept header as demonstrated below.

Plain Text

Plain text is the default Advice Content Type. When retrieving plain text, the following MIME types (including the two custom ones) are equivalent.

  Accept: application/json
  Accept: application/vnd.taffrail.json
  Accept: application/vnd.taffrail.json+text // preferred

Example of plain text Advice using this header:

{
  "headline": "Use a Roth IRA when single and your income is below $146,000"
}

HTML

๐Ÿ’…

The HTML Advice Content Type is probably what you want

Our clients prefer the HTML it-just-works response format.

To request formatted HTML, use the +html modifier on the Accept header as follows. Note that the plain text field will always be returned, and a new _html field appears.

 Accept: application/vnd.taffrail.json+html

Example of Advice using this header:

{
  "headline": "Use a Roth when single and your income is below $146,000",
  "headline_html": "<h1 id=\"taffrail-use-a-roth-when-single-and-your-income-is-below-146000\" data-tf=\"5wYgjI4DyxtIjeRuCXNtP\">Use a Roth when <taffrail-var data-variable-name=\"Tax_Filing_Status\" data-variable-id=\"kxJJOeGun3weVjA74lKtk\" data-variable-type=\"Freetext\" data-variable-raw-value=\"single\">single</taffrail-var> and your income is below <taffrail-var data-variable-name=\"IRS_Limit_Roth_Single_Income_Low\" data-variable-id=\"8laeFmYB4eTtHX-AxmnaZ\" data-variable-type=\"Number\" data-variable-format=\"$0,0\" data-variable-raw-value=\"146000\">$146,000</taffrail-var></h1>\n"
}

If the HTML response includes a hyperlinked element, that indicates the linked phrase is associated with a Variable in an Input Request. In the example above, "when single" would be linked to the Input Request that assigns Tax_Filing_Status.

Your HTML renderer is responsible for attaching appropriate interface events to show the linked Input Request to the user through the chip. For more information on chips, refer to our demo and Taffrailโ€™s Style Guide.

๐Ÿ“˜

Backlinks

A Backlink is used to link a Variable in Advice text to the assumption (or originating question) where the user could modify the input.

Read more about Backlinks.

HTML without hyperlinks

Requesting Advice content formatted explicitly as HTML without hyperlinked Backlinks is possible. This is commonly used for printing tearsheets or static PDF generation where hyperlinks may detract from the final product.

To request formatted HTML without links, use the +htmlnolinks modifier on the Accept header as follows. Note that the plain text field will always be returned, and a new _html field appears.

 Accept: application/vnd.taffrail.json+htmlnolinks

You will notice Taffrail Variables are still defined as Web Components in the response.

{
  "headline": "Use a Roth when single and your income is below $146,000",
  "headline_html": "<h1 id=\"taffrail-use-a-roth-when-single-and-your-income-is-below-146000\" data-tf=\"5wYgjI4DyxtIjeRuCXNtP\">Use a Roth when <taffrail-var data-variable-name=\"Tax_Filing_Status\" data-variable-id=\"kxJJOeGun3weVjA74lKtk\" data-variable-type=\"Freetext\" data-variable-raw-value=\"single\">single<\/taffrail-var> and your income is below <taffrail-var data-variable-name=\"IRS_Limit_Roth_Single_Income_Low\" data-variable-id=\"8laeFmYB4eTtHX-AxmnaZ\" data-variable-type=\"Number\" data-variable-format=\"$0,0\" data-variable-raw-value=\"146000\">$146,000<\/taffrail-var><\/h1>\n"
}

Plain Text with AttributedString Support

To request text with a list of attributions for use in AttributedString structs (found in iOS and Android, among others), use the +attrstring modifier on the Accept header as follows. Note that the plain text field will always be returned, and a new [field]_attributes field appears.

  Accept: application/vnd.taffrail.json+attrstring

Example of Advice using this header illustrating a Backlink attribution:

{
  "headline": "Use a Roth when single and your income is below $146,000",
  "headline_attributes": [
    {
      "range": {
        "indexStart": 16,
        "length": 6,
        "indexEnd": 22
      },
      "value": "single",
      "type": "backlink",
      "variable": "Tax_Filing_Status"
    },
    {
      "range": {
        "indexStart": 48,
        "length": 8,
        "indexEnd": 56
      },
      "value": 146000,
      "valueFormatted": "$146,000",
      "type": "backlink",
      "variable": "IRS_Limit_Roth_Single_Income_Low",
    }
  ]
}

Notes on the [field]_attribution objects:

  • The range property's object contains the attribution's start, end, and length.
  • The id property's value is the Variable ID for cross-referencing the Variables list.
  • If a type property exists in the [field]_attributes items, its value is an enum of format, backlink, and formulaic.
  • If there are no attributions in a string, the [field]_attributes property will not exist.

Formats & Backlinks

Formatted Text

If the [field]_attributes property contains an entry with "type": "format", that indicates a fragment should be formatted according to the value of the format property. See below for an example.

Theformat property value is an enum of bold, italic, and indeterminate.

Example of an Input Request using this header illustrating a Format attribution:

{
  "question": "How much are your **monthly** living expenses?",
  "question_attributes": [
    {
      "range": {
        "indexStart": 18,
        "indexEnd": 25,
        "length": 7
      },
      "format": "bold",
      "value": "monthly",
      "type": "format"
    }
  ]
}

Backlinks

If the [field]_attributes property contains an entry with"type": "backlink", that indicates a phrase is associated with a Variable in an Input Request. In the example farther above, "income is below $146,000" would be linked to the Input Request that assigns IRS_Limit_Roth_Single_Income_Low.

If the type is formulaic, that indicates a Variable was found in the string and it does not have an associated Input Request. You can choose to attribute or style the Variable or not.

๐Ÿ“˜

Backlinks

A Backlink is used to link a Variable in Advice text to the Assumption (or originating question) where the user could modify the input. This should be displayed as a "chip" on the interface.

Read more about Backlinks.


Markdown

Unparsed (raw) Markdown syntax support is coming in a future release.


Raw

To request unformatted raw Advice content without variable values resolved, use the +raw modifier on the Accept header as follows.

๐Ÿšง

This format is only useful when debugging or implementing a custom interface and parsing engine.

  Accept: application/vnd.taffrail.json+raw

Example of Advice using this header.

{
  "headline": "# Use a Roth when {{Tax_Filing_Status}} and your income is below {{IRS_Limit_Roth_Single_Income_Low}}"
}