Actionable Insights

Summary

Actionable insights are designed to give you timely insights into your customers' financial health and provide you with enough information to notify your customer of what is happening in their financial lives. The insights are split into three logical groups;

GET insights/v1/actionable/balances endpoint - Provides a list of insights relevant to a customer's balances
GET insights/v1/actionable/income endpoint - Provides a list of insights relevant to a customer's income
GET insights/v1/actionable/spending endpoint - Provides a list of insights relevant to a customer's spending

Each of these insights is accompanied by a details endpoint which can be used to retrieve all the relevant accounts/transactions that were used to generate the insight. It's not intended for you to subsequently hit the details endpoint each time you generate an insight for your customer but rather it can be used if you would like to show the associated accounts/transactions to an insight or for testing purposes during your integration with Bud.

For each of the endpoints, you have the option whether to return all applicable insights for the customer or to specify which insights are of interest to you. This can be done using the enabled_insights query parameter in the request. See example below.

curl --request GET \
     --url 'https://api-sandbox.thisisbud.com/insights/v1/actionable/balances?enabled_insights=in_overdraft' \
     --header 'accept: application/json'

Webhooks

For some actionable insights, webhooks are available to notify you when an insight has been triggered. You can find out more about the available webhooks in the engage webhooks guide

Thresholds

Most of the insights have thresholds for triggering that insight; for example with low_balance, you can set the balance amount from where this triggers. By default, there are Bud thresholds but you can also update these thresholds for a given project by logging a support request.

These thresholds (default or specified) will be used at the point of initial account connection or any subsequent data ingestion to calculate all the applicable insights for the given customer, by hitting one of the insights endpoints you will then be retrieving these pre-calculated insights.

🚧
You can also specify thresholds on an individual request by sending query parameters, however, this will require the insight to be recalculated with the new threshold meaning latency will be drastically increased.

Retrieve Balances Actionable Insights

We currently have four actionable insights related to a customer's balance.

Insight	Description	Default Threshold	Threshold Description
`close_to_credit_limit`	The customer's credit card utilization exceeds the configured threshold on a single credit card account. This insight is only applicable to credit card accounts, not checking or savings accounts.	70%	Percentage utilization - the minimum credit utilization before the insight is triggered calculated as current balance divided by credit limit
`low_balance`	The balance of an individual checking account has fallen below the configured threshold. This insight is triggered per account and is not based on the customer’s total balance across accounts.	$50	Balance threshold - the balance amount whereby any value lower will trigger the insight
`in_overdraft`	The balance of a single checking account has fallen below 0. This insight is triggered per account and is not based on the customer’s total balance across accounts.	-	-
`cannot_cover_bills`	The balance of a single checking or savings account will not be enough to cover upcoming bills after predicted bills and other future transactions are accounted for. This insight applies per account, and considers only the balance and predicted activity of the specific account it is linked to.	-	-

An example of a successful 200 response can be seen below.

{
  "operation_id": "insights_v1_actionable_balances_get",
  "data": {
    "insights": [
      {
        "id": "in_overdraft_8789764a-df2f-4589-b550-00bcd0e9cb2c",
        "type": "in_overdraft",
        "account_id": "8789764a-df2f-4589-b550-00bcd0e9cb2c",
        "balance": {
          "value": "100.00",
          "currency": "USD",
          "credit_debit_indicator": "debit"
        },
        "threshold": {
          "value": "0.00",
          "currency": "USD",
          "credit_debit_indicator": "debit"
        },
        "_links": {
          "details": "https://domain/insights/v1/actionable/balances/in_overdraft/in_overdraft_8789764a-df2f-4589-b550-00bcd0e9cb2c/details"
        }
      }
    ]
  },
  "metadata": {
    "results": 1,
    "from": "2022-11-01T00:00:00Z",
    "to": "2023-05-16T17:30:00Z",
    "options": []
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/insights/v1/actionable/balances \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

The response contains all applicable insights for the given customer that have been triggered, each insight will contain the account_id, balance and a link to the details endpoint.

An example of the response of the details endpoint can be seen below.

{
  "operation_id": "insights_v1_actionable_balances_details_get",
  "data": {
    "id": "in_overdraft_ee7a2d6a-2baa-461a-aca2-844e88a3f3e7",
    "type": "in_overdraft",
    "caused_by": {
      "accounts": [
        {
          "account_id": "ee7a2d6a-2baa-461a-aca2-844e88a3f3e7",
          "currency": "USD",
          "holder": {
            "name": "David Smith",
            "relationship": "unknown"
          },
          "account_name": "My Checking Account",
          "account_type": "current_account",
          "usage_type": "personal",
          "provider": "BankOfBud",
          "identifiers": {
            "pan": "1234567890"
          },
          "balances": [
            {
              "date": "2023-05-12T00:00:00Z",
              "amount": {
                "value": "100.00",
                "currency": "USD"
              },
              "type": "interim_booked",
              "credit_debit_indicator": "debit"
            },
            {
              "date": "2023-05-12T00:00:00Z",
              "amount": {
                "value": "100.00",
                "currency": "USD"
              },
              "type": "expected",
              "credit_debit_indicator": "debit"
            }
          ],
          "credit_lines": [
            {
              "date": "2023-05-12T00:00:00Z",
              "type": "credit",
              "amount": {
                "value": "1000.00",
                "currency": "USD"
              }
            }
          ]
        }
      ],
      "transactions": []
    },
    "details": {}
  },
  "metadata": {
    "from": "2022-11-01T00:00:00Z",
    "to": "2023-05-16T17:30:00Z",
    "options": []
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/insights/v1/actionable/balances/%3Cin_overdraft%3E/%3Clate_income_8789764a%3E/details \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

The details response contains extra information about the accounts including account_name, holder, identifiers and provider.

If you receive an error please consult the error responses guide.

Retrieve Income Actionable Insights

We currently have four actionable insights related to a customer's income.

Insight	Description	Default Threshold	Threshold Description
`late_income`	A customer's regular income is later than we have predicted	3 days / greater than $10	Days late - the number of days that will pass after the forecasted transaction date before the insight is triggered Minimum value - the minimum value that the forecasted transaction can be for
`gambling_income`	A customer has credit transactions from a known gambling company	$100 / greater than 5% of income	Minimum Monthly - the minimum monthly absolute total before the insight will trigger Percentage total - the minimum percentage of all income that must be gambling income for the insight to trigger
`pension_income`	A customer has credit transactions that are categorized as retirement or pension income	$500 / greater than 5% of income	Minimum Monthly - the minimum monthly absolute total before the insight will trigger Percentage total - the minimum percentage of all income that must be pension income for insight to trigger
`regular_income_changed`	Identifies where regular income has increased or decreased in value compared to the previous month's income	5% / greater than $1	Absolute change - the minimum absolute change between the previous and latest transaction amounts of a regular payment Percentage change - the minimum percentage change between the previous and latest amounts of a regular payment

An example of a successful 200 response can be seen below.

{
  {
  "operation_id": "insights_v1_actionable_income_get",
  "data": {
    "insights": [
      {
        "id": "late_income_8789764a-df2f-4589-b550-00bcd0e9cb2c",
        "type": "late_income",
        "transactions": [
          {
            "transaction_id": "a_transaction_id",
            "account_id": "ee7a2d6a-2baa-461a-aca2-844e88a3f3e7",
            "provider": "BankOfBud",
            "description": "SALARY",
            "credit_debit_indicator": "credit",
            "status": "booked",
            "amount": {
              "value": "3000.00",
              "currency": "USD"
            },
            "date_time": "2023-04-10T10:00:00Z",
            "enrichments": {
              "categories": {
                "l1": {
                  "slug": "income",
                  "confidence": "0.99"
                },
                "l2": {
                  "slug": "employment_income",
                  "confidence": "0.98"
                }
              },
              "regularity": {
                "slug": "monthly",
                "confidence": "0.99",
                "predicted_date_times": {
                  "date_time": "2023-05-10T10:00:00Z"
                }
              }
            }
          }
        ],
        "_links": {
          "details": "https://domain/insights/v1/actionable/income/late_income/late_income_8789764a-df2f-4589-b550-00bcd0e9cb2c/details"
        }
      }
    ],
    "totals": {
      "income": [
        {
          "value": "12000.00",
          "currency": "USD"
        }
      ],
      "expenditure": [
        {
          "value": "14000.00",
          "currency": "USD"
        }
      ]
    }
  },
  "metadata": {
    "results": 1,
    "from": "2022-11-01T00:00:00Z",
    "to": "2023-05-16T17:30:00Z",
    "options": [
      {
        "insight_type": "late_income",
        "option": "minimum_days_late_threshold",
        "value": "3"
      },
      {
        "insight_type": "late_income",
        "option": "minimum_value_threshold",
        "value": "100.00"
      }
    ]
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/insights/v1/actionable/income \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

The response contains all applicable insights for the given customer that have been triggered, each insight will contain a list of transactions and a link to the details endpoint.

An example of the response of the details endpoint can be seen below.

{
  "operation_id": "insights_v1_actionable_income_details_get",
  "data": {
    "id": "late_income_8789764a-df2f-4589-b550-00bcd0e9cb2c",
    "type": "late_income",
    "caused_by": {
      "accounts": [
        {
          "account_id": "ee7a2d6a-2baa-461a-aca2-844e88a3f3e7",
          "currency": "USD",
          "holder": {
            "name": "David Smith",
            "relationship": "unknown"
          },
          "account_name": "My Checking Account",
          "account_type": "current_account",
          "usage_type": "personal",
          "provider": "BankOfBud",
          "identifiers": {
            "pan": "1234567890"
          },
          "balances": [
            {
              "date": "2023-05-12T00:00:00Z",
              "amount": {
                "value": "3552.61",
                "currency": "USD"
              },
              "type": "interim_booked",
              "credit_debit_indicator": "credit"
            },
            {
              "date": "2023-05-12T00:00:00Z",
              "amount": {
                "value": "3552.61",
                "currency": "USD"
              },
              "type": "expected",
              "credit_debit_indicator": "credit"
            }
          ],
          "credit_lines": [
            {
              "date": "2023-05-12T00:00:00Z",
              "type": "credit",
              "amount": {
                "value": "1000.00",
                "currency": "USD"
              }
            }
          ]
        }
      ],
      "transactions": [
       {
            "transaction_id": "a_transaction_id",
            "account_id": "ee7a2d6a-2baa-461a-aca2-844e88a3f3e7",
            "provider": "BankOfBud",
            "description": "SALARY",
            "credit_debit_indicator": "credit",
            "status": "booked",
            "amount": {
              "value": "3000.00",
              "currency": "USD"
            },
            "date_time": "2023-04-10T10:00:00Z",
            "enrichments": {
              "categories": {
                "l1": {
                  "slug": "income",
                  "confidence": "0.99"
                },
                "l2": {
                  "slug": "employment_income",
                  "confidence": "0.98"
                }
              },
              "regularity": {
                "slug": "monthly",
                "confidence": "0.99",
                "predicted_date_times": {
                  "date_time": "2023-05-10T10:00:00Z"
                }
              }
            }
          }
      ]
    },
    "details": {
      "days_late": 6,
      "expected_date_time": "2023-05-10T10:00:00Z"
    }
  },
  "metadata": {
    "from": "2022-11-01T00:00:00Z",
    "to": "2023-05-16T17:30:00Z",
    "options": [
      {
        "insight_type": "late_income",
        "option": "minimum_days_late_threshold",
        "value": "3"
      },
      {
        "insight_type": "late_income",
        "option": "minimum_value_threshold",
        "value": "100.00"
      }
    ]
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/insights/v1/actionable/income/%3Clate_income%3E/%3Clate_income_878954a%3E/details \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

The details response contains extra information about the accounts including account_name, holder, identifiers, provider and any relevant transactions.

If you receive an error please consult the error responses guide.

Retrieve Spending Actionable Insights

We currently have four actionable insights related to a customer's spending.

Insight	Description	Default Threshold	Threshold Description
`new_insurance_expense`	We have identified a new insurance expense in a customer's transactions	-	-
`suspected_duplicate_charge`	A customer has one or more debit transactions with the same description, amount and on the same day	-	-
`regular_payment_changed`	Identifies where regular payments have increased or decreased in value compared to the previous month's value	5% / greater than $1	Percentage change - the minimum percentage change between the previous and latest transaction amounts of a regular payment Absolute change - the minimum absolute change between the previous and latest transaction amounts of a regular payment
`late_payment`	A forecasted payment that we would predict through regular transactions has not been completed	3 days / greater than $10	Days late - the number of days that will pass after the forecasted transaction date before the insight is triggered Minimum value - the minimum value that the forecasted transaction can be for

An example of a successful 200 response can be seen below.

{
  "operation_id": "insights_v1_actionable_spending_get",
  "data": {
    "insights": [
      {
        "id": "late_payment_8789764a-df2f-4589-b550-00bcd0e9cb2c",
        "type": "late_payment",
        "transactions": [
          {
            "transaction_id": "a_transaction_id",
            "account_id": "ee7a2d6a-2baa-461a-aca2-844e88a3f3e7",
            "provider": "BankOfBud",
            "description": "MORTGAGE",
            "credit_debit_indicator": "debit",
            "status": "booked",
            "amount": {
              "value": "1400.00",
              "currency": "USD"
            },
            "date_time": "2023-04-10T10:00:00Z",
            "enrichments": {
              "categories": {
                "l1": {
                  "slug": "mortgage_and_rent",
                  "confidence": "0.99"
                },
                "l2": {
                  "slug": "mortgage",
                  "confidence": "0.98"
                }
              },
              "regularity": {
                "slug": "monthly",
                "confidence": "0.99",
                "predicted_date_times": {
                  "date_time": "2023-05-10T10:00:00Z"
                }
              }
            }
          }
        ],
        "_links": {
          "details": "https://domain/insights/v1/actionable/spending/late_income/late_income_8789764a-df2f-4589-b550-00bcd0e9cb2c/details"
        }
      }
    ],
    "totals": {
      "income": [
        {
          "value": "12000.00",
          "currency": "USD"
        }
      ],
      "expenditure": [
        {
          "value": "14000.00",
          "currency": "USD"
        }
      ]
    }
  },
  "metadata": {
    "results": 1,
    "from": "2022-11-01T00:00:00Z",
    "to": "2023-05-16T17:30:00Z",
    "options": [
      {
        "insight_type": "late_payment",
        "option": "minimum_days_late_threshold",
        "value": "3"
      },
      {
        "insight_type": "late_payment",
        "option": "minimum_value_threshold",
        "value": "100.00"
      }
    ]
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/insights/v1/actionable/spending \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

The response contains all applicable insights for the given customer that have been triggered, each insight will contain a list of transactions, a totals object detailing the customers total income and expenditure and a link to the details endpoint.

An example of the response of the details endpoint can be seen below.

{
  "operation_id": "insights_v1_actionable_spending_details_get",
  "data": {
    "id": "late_payment_8789764a-df2f-4589-b550-00bcd0e9cb2c",
    "type": "late_payment",
    "caused_by": {
      "accounts": [
        {
          "account_id": "ee7a2d6a-2baa-461a-aca2-844e88a3f3e7",
          "currency": "USD",
          "holder": {
            "name": "David Smith",
            "relationship": "unknown"
          },
          "account_name": "My Checking Account",
          "account_type": "current_account",
          "usage_type": "personal",
          "provider": "BankOfBud",
          "identifiers": {
            "pan": "1234567890"
          },
          "balances": [
            {
              "date": "2023-05-12T00:00:00Z",
              "amount": {
                "value": "3552.61",
                "currency": "USD"
              },
              "type": "interim_booked",
              "credit_debit_indicator": "credit"
            },
            {
              "date": "2023-05-12T00:00:00Z",
              "amount": {
                "value": "3552.61",
                "currency": "USD"
              },
              "type": "expected",
              "credit_debit_indicator": "credit"
            }
          ],
          "credit_lines": [
            {
              "date": "2023-05-12T00:00:00Z",
              "type": "credit",
              "amount": {
                "value": "1000.00",
                "currency": "USD"
              }
            }
          ]
        }
      ],
      "transactions": [
       {
            "transaction_id": "a_transaction_id",
            "account_id": "ee7a2d6a-2baa-461a-aca2-844e88a3f3e7",
            "provider": "BankOfBud",
            "description": "MORTGAGE",
            "credit_debit_indicator": "debit",
            "status": "booked",
            "amount": {
              "value": "1400.00",
              "currency": "USD"
            },
            "date_time": "2023-04-10T10:00:00Z",
            "enrichments": {
              "categories": {
                "l1": {
                  "slug": "mortgage_and_rent",
                  "confidence": "0.99"
                },
                "l2": {
                  "slug": "mortgage",
                  "confidence": "0.98"
                }
              },
              "regularity": {
                "slug": "monthly",
                "confidence": "0.99",
                "predicted_date_times": {
                  "date_time": "2023-05-10T10:00:00Z"
                }
              }
            }
          }
      ]
    },
    "details": {
      "days_late": 6,
      "expected_date_time": "2023-05-10T10:00:00Z"
    }
  },
  "metadata": {
    "from": "2022-11-01T00:00:00Z",
    "to": "2023-05-16T17:30:00Z",
    "options": [
      {
        "insight_type": "late_payment",
        "option": "minimum_days_late_threshold",
        "value": "3"
      },
      {
        "insight_type": "late_payment",
        "option": "minimum_value_threshold",
        "value": "10.00"
      }
    ]
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/insights/v1/actionable/spending/type/id/details \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

The details response contains extra information about the accounts including account_name, holder, identifiers and provider and any relevant transactions.

If you receive an error please consult the error responses guide.

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.