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'

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
`close_to_credit_limit`	The customer's credit utilization exceeds the given threshold for a single account	70%
`low_balance`	The customer's account balance has fallen below the given threshold	$50
`in_overdraft`	One or more of the customer's accounts has a balance lower than 0	-
`cannot_cover_bills`	The customer is likely to have a negative account balance at the end of the month after paying their bills, taking into account predicted future transactions and the current account balance	-

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
`late_income`	A customer's regular income is later than we have predicted	3 days / greater than $10
`gambling_income`	A customer has credit transactions from a known gambling company	$100 / greater than 5% of income
`pension_income`	A customer has credit transactions that are categorized as retirement or pension income	$500 / greater than 5% of income
`regular_income_changed`	Identifies where regular income has increased or decreased in value compared to the previous month's income	5% / greater than $1

📘
Please note the absolute thresholds for gambling_income and pension_income of $100 and $500 are per month.

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
`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
`late_payment`	A forecasted payment that we would predict through regular transactions has not been completed	3 days / greater than $10

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.