Global account filtering

Bud widgets support global account filtering via the Selected Accounts endpoints. This guide will explain how you can create your own global account filter when displaying widgets within your own application.

Within Bud's widgets, a customer can set a list of selected accounts. When a list is set, only data related to those accounts is taken into consideration when the widgets render.

How selected accounts work

Selected accounts are stored per customer. Each time you set the list, it replaces any list already stored for that customer. At least one account must always be selected, so an empty list is never stored or returned.

Retrieve the customer's accounts

Before you set the list of selected accounts, you need to know which accounts the customer has access to. Use the Retrieve Accounts V3 endpoint to fetch them.

Each account in the response includes an account_id. This is the value you use when setting the list of selected accounts.

Each account also includes a suggested_name. This is the suggested label to show alongside the account when you display the list to users, and it is how accounts are referenced within Bud's widgets.

📘

Using account_id and suggested_name

Use account_id to identify accounts in requests to the Preferences endpoints, and suggested_name to label them in your own interface. Using the same label as the widgets keeps the experience consistent for your customers.

With this information, you can render a component that lets customers choose which accounts they want to see data for. The two endpoints below allow you to read and set that selection.

Retrieve the selected accounts

The Retrieve Selected Accounts User's Preferences endpoint returns the list of accounts currently selected by the customer.

GET /preferences/v1/selected-accounts

You must identify the customer using either the X-Customer-Id header or the X-Customer-Idempotent-Identifier header. The X-Customer-Idempotent-Identifier header takes the internal client identifier provided in the client_metadata object when you created the customer using Create Customer V3.

curl --request GET \
     --url https://api-sandbox.thisisbud.com/preferences/v1/selected-accounts \
     --header 'Authorization: Bearer <access_token>' \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

A successful request returns a 200 status code and the list of selected account_id values in the data array:

{
  "operation_id": "preferences_v1_select_accounts_get",
  "data": [
    "selected_account_1",
    "selected_account_2"
  ]
}

If no list has been stored for the customer, the endpoint returns a 404. An empty list is never returned, as at least one account must always be selected.

Set the selected accounts

The Modify list of selected accounts endpoint sets the list of accounts selected by the customer. The request body is an array of account_id values.

POST /preferences/v1/selected-accounts

As with the retrieve endpoint, identify the customer using either the X-Customer-Id header or the X-Customer-Idempotent-Identifier header.

curl --request POST \
     --url https://api-sandbox.thisisbud.com/preferences/v1/selected-accounts \
     --header 'Authorization: Bearer <access_token>' \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'content-type: application/json' \
     --data '
[
  "selected_account_1",
  "selected_account_2"
]
'

A successful request returns a 204 status code with no response body.

📘

The list is replaced, not appended to

Each request replaces the list already stored for the customer. To add or remove an account, send the complete list of accounts that should be selected.

The list must include at least one account_id. If the list is empty, Bud returns a 400 validation error:

{
  "operation_id": "preferences_v1_select_accounts_post",
  "code_id": "failed_validation",
  "message": "Invalid request payload.",
  "errors": {
    "accounts": "The list of selected accounts cannot be empty"
  }
}

Enable syncing across widgets

For a widget to use the customer's selected accounts, append the enable_user_preferences_sync parameter to the widget URL:

https://widgets.thisisbud.com/<widget_path>?token=<token>&enable_user_preferences_sync

The parameter must be added to each widget URL individually, which gives you the flexibility to choose which widgets sync with the customer's preferences and which do not.

📘

Accounts Widget

The Accounts Widget is the only widget that does not support syncing with selected accounts. It always displays every account the customer has ingested into the Bud platform.

Putting it together

To implement your own global account filter:

1. Call Retrieve Accounts V3 to fetch the customer's accounts, using account_id as the identifier and suggested_name as the label.
2. Render a component that lets the customer choose which accounts to include.
3. Call the Modify list of selected accounts endpoint with the chosen account_id values.
4. Append enable_user_preferences_sync to the URL of each widget that should respect the selection.
5. Call the Retrieve Selected Accounts endpoint whenever you need to display the customer's current selection.