Customer-Level Insights

Summary

Before starting you'll need a valid OAuth access token. For further details on how to authenticate to Bud's APIs please see this guide.

Customer-level insights tell you which characteristics apply to a customer, and give you key values measured from their financial data. There are two kinds:

Flags say whether a characteristic applies to the customer, such as whether they're a Credit card user. Each flag has an id, a display_name, a description and a matched value of true or false.
Facts are single values measured from the customer's data, such as their total income. Each fact has a name, a description and, where one applies, a value.

The flags and facts available are configured for your API client. Contact your Bud representative to change which ones are enabled. They can be retrieved using four endpoints:

GET insights/v1/customer-level/flags endpoint - Provides every flag available to you, with whether the customer matched it
GET insights/v1/customer-level/flags/{flag_id} endpoint - Provides a single flag
GET insights/v1/customer-level/facts endpoint - Provides every fact available to you, with its value for the customer where one applies
GET insights/v1/customer-level/facts/{fact_name} endpoint - Provides a single fact

Insights are recalculated from the customer's current data every time you request them, so they change as new data arrives for the customer. We'd recommend retrieving them again after ingesting new data or refreshing a connection, rather than storing them.

Retrieve Customer-Level Flags

Each flag uses the time window set in its own criteria, so different flags can look at different periods. A flag's description tells you what it identifies.

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

{
  "operation_id": "v1_organisation_customer_flags_list",
  "data": [
    {
      "id": "credit_card_user",
      "display_name": "Credit card user",
      "description": "Customers that make credit card repayments or have a credit card account",
      "matched": true
    },
    {
      "id": "ad_hoc_saver",
      "display_name": "Ad-hoc saver",
      "description": "Customers who save irregularly, with savings amounts that vary significantly month to month",
      "matched": false
    }
  ]
}

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

If you only need the flags the customer matched, use the matched=true query parameter. Only flags where matched is true are returned.

curl --request GET \
     --url 'https://api-sandbox.thisisbud.com/insights/v1/customer-level/flags?matched=true' \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

A flag's id is the same for every customer under your API client. Use it as the {flag_id} in the single flag endpoint when you only need one result: only that flag is calculated, and the response contains that flag in the same shape as an item in the list.

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

Retrieve Customer-Level Facts

Facts are calculated over the most recent three months of the customer's data.

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

{
  "operation_id": "v1_organisation_customer_facts_list",
  "data": [
    {
      "name": "total_income",
      "description": "Total income received by the customer in the specified time period.",
      "value": 12750.00
    },
    {
      "name": "mean_income",
      "description": "Income of the customer in the specified time period, averaged by table time interval.",
      "value": 4250.00
    },
    {
      "name": "has_mortgage",
      "description": "Indicates whether the customer has at least 1 mortgage transaction in the specified time period. Does not say who the mortgage is with.",
      "value": true
    }
  ]
}

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

A fact's value is a number, a string or a boolean, depending on the fact.

📘
Missing Value Handling
When a fact has no value for the customer, value is left out of the response. For example, a fact giving the date a customer's balance is projected to go negative has no value for a customer whose balance never does. Treat a missing value as the fact not applying to this customer, rather than as an error.

A fact's name is the same for every customer under your API client. Use it as the {fact_name} in the single fact endpoint when you only need one result: only that fact is calculated, and the response contains that fact in the same shape as an item in the list.

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

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.