Advice Content Types

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

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

• Plain text
• HTML
• HTML without hyperlinks
• Markdown (coming in a future release)
• Raw

⏩

Most of our API clients prefer the HTML formatted response content type

The API's 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.

📘

A note on the response body

All but a few endpoints will return a response body. Unless stated otherwise, the response body is in JSON format. Blank fields are omitted rather than being included with a null value. All timestamps are returned in UTC time, following the ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Plain Text

Plain text is the default Advice Content Type. When retrieving plain text, use the following MIME type:

  Accept: application/vnd.taffrail.json+text

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 [fieldName]_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"
}

Your HTML renderer is responsible for rendering the HTML as provided and attaching appropriate interface events to show the user Backlinks (hyperlinks referencing Input Requests) through the chip interface. 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 [fieldName]_html field appears.

 Accept: application/vnd.taffrail.json+htmlnolinks

You will notice Taffrail Variables are still defined as Web Components in the response, but there are no hyperlinks. The <taffrail-var> element will contain a data-backlink-required="true" attribute which can be used to style the Backlink in its static state.

{
  "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"
}

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. Do not use unless instructed to do so.

  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}}"
}