The Advice API is designed to be a ”one-stop shop” for fetching Advice and recommendations, the details about the rules behind that advice, and all the data that makes the advice possible.

The API is RESTful and communicates in JSON. Additionally, the API is stateless. That is each request is treated as individual and unique knowing nothing about the previous request, even if it is generated by the same user.

Components of the API

The response of the Advice API consists of a handful of components which are described below.

Errors

A set of defined and well-formed errors indicate issues in the API. In the API Reference, you will see all the error types. For now, it is important to note if the API returns an error it is likely not a server error (HTTP 500) but rather an issue our Rules Engine encountered with certain inputs (or lack thereof). In those scenarios, an HTTP 200 status code will be sent in the response.

Advice Set

This property includes details about the Advice Set, its metadata, associated references, category data, and more.

Advice

The Advice property is where the magic happens. It contains a list of all the relevant inputs required (in the form of questions for a user) and all the Advice the Advice Set generated.

There are two types of objects included in the Advice list.

Input Requests

Input Requests are what the API returns for every piece of required and relevant input data. For example, if a given Advice Set needs the user's approximate income (e.g., to check IRA eligibility), the API will indicate Input Needed (reference) and specify the field name, possible allowed values, if any, formatting rules, and more. In this scenario, the Rules Engine cannot continue through the rules until more data is provided.

📘

Smart Defaults and Known Data

Common API integrations will have some Input Requests shown to users in a form (e.g., "Is your income higher or lower than $125,000/year?" with Yes/No options) combined with other Input Requests programmatically bypassed by using known data (e.g., Married = true) and/or setting smart defaults (e.g., Retirement_Age = 67).

Advice

The API returns Advice objects for everything that should be shown to a user. This is primarily text-based content (e.g., "You are eligible for a Roth IRA") but can include detailed summaries, attachments, actions (e.g., external links), logical grouping buckets, and more.

Our Rules Engine creates a breadcrumb of Advice as it processes rules leading to more relevant and actionable outcomes for users.

Advice Content Types

Advice Builder supports writing Advice in Markdown syntax. The Advice API is capable of returning parsed Markdown (i.e., structured HTML) and an HTML renderer (i.e., a web browser) would be required where Advice is to be displayed.

In a future version of our API, we will be adding an option to return unparsed (raw) Markdown.

Read more about Advice Content Types in the Basics.

Variables

All of the data necessary to make the Advice possible is contained in the Variables property. This data is critical for building interactive interfaces, managing state, and tracking non-textual API outputs.