---
updatedAt: 2025-09-26T08:55:52.000Z
agentTools:
  projectIndex: https://docs-us.thisisbud.com/llms.txt
---

# Intelligent Search

### What is Intelligent Search?

The Intelligent Search API allows you to show a list of enriched transactions to your customers, with AI powered semantic search and generated financial insights based on those transactions. If you're wanting to utilise the Intelligent Search widget please read our other guide [here](https://docs-us.thisisbud.com/docs/intelligent-search).

## Displaying and searching transactions

Calling [GET search/beta/transactions](https://docs-us.thisisbud.com/reference/search_beta_transactions_get) with an empty `user_input` will return a list of your customer's most recent transactions. The transaction body will be the same as [GET financial/v2/transactions](https://docs-us.thisisbud.com/reference/v2_transactions_get-1), and the api response contains the latest 25 transactions by default (unless the `page_size` query param is set otherwise). If you would like your customers to view the next set of transactions you can do so by using the `next_page_token` found in the previous response.

Once your customer is ready to search through their transactions you can do so by entering an input into the `user_input` query param. This supports full free text search powered by generative AI, for example `groceries`, `starbucks` or `car` as well as questions such as `how much did I spend on groceries in March?`. Partial inputs such as `groc` or `starb`will also work, although as a user provides more information the more precise the search results will be.

In addition to the `user_input` there are are number of ways to filter transactions such as by category, merchant, `account_id`, date, amount or `credit_debit_indicator`. These filters are exact match filters and work like standard filters in other Bud endpoints.

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

```Text json Response
{
  "operation_id": "search_beta_transactions_get",
  "data": {
    "id": "8a567b41-1b61-4f8f-a1ea-8fcb10d08d9f",
    "results": [
      {
        "matches": [
          {
            "type": "merchant_name",
            "content": "Dunkin'"
          },
          {
            "type": "category_l2",
            "content": "coffee"
          }
        ],
        "transaction": {
          "transaction_id": "378",
          "account_id": "5ce0749e-551c-4693-87f8-400d2551fdd1",
          "provider": "Chase",
          "description": "DUNKIN DONUTS COFFEE BROOKLYN NEW YORK",
          "credit_debit_indicator": "debit",
          "amount": {
            "value": "8.87",
            "currency": "USD"
          },
          "date_time": "2025-03-02T00:00:00Z",
          "posted_date_time": "2025-03-02T00:00:00Z",
          "status": "booked",
          "suggested_description": "Dunkin'",
          "suggested_logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg",
          "enrichments": {
            "merchant": {
              "id": "ba8ef908-b624-4116-8b26-571e48d1bf4c",
              "slug": "dunkin",
              "display_name": "Dunkin'",
              "logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg",
              "website": "https://www.dunkindonuts.com",
              "tokens": [
                {
                  "confidence": "1.00",
                  "value": "DUNKIN DONUTS COFFEE"
                }
              ]
            },
            "categories": {
              "l1": {
                "slug": "food_and_drink",
                "confidence": "0.98"
              },
              "l2": {
                "slug": "coffee",
                "confidence": "0.96"
              }
            },
            "regularity": {
              "frequency": "biweekly",
              "predicted_date_times": [
                "2025-03-17T00:00:00Z",
                "2025-03-31T00:00:00Z",
                "2025-04-14T00:00:00Z",
                "2025-04-28T00:00:00Z",
                "2025-05-12T00:00:00Z",
                "2025-05-27T00:00:00Z",
                "2025-06-09T00:00:00Z",
                "2025-06-23T00:00:00Z"
              ],
              "group_label": "3e1b2ea4df1579fe9dcda6cf6b032492d8551e78404d023ca3d57ca8b1ae2159-4"
            },
            "location": {
              "address": {
                "city": "New York",
                "region": "NY",
                "country": "US"
              },
              "geolocation": {
                "longitude": -73.9872777778,
                "latitude": 40.6919444444
              }
            }
          },
          "tags": [
            "regular-transaction"
          ]
        }
      },
      {
        "matches": [
          {
            "type": "merchant_name",
            "content": "Dunkin'"
          },
          {
            "type": "category_l2",
            "content": "coffee"
          }
        ],
        "transaction": {
          "transaction_id": "377",
          "account_id": "5ce0749e-551c-4693-87f8-400d2551fdd1",
          "provider": "Chase",
          "description": "DUNKIN DONUTS COFFEE BROOKLYN NEW YORK",
          "credit_debit_indicator": "debit",
          "amount": {
            "value": "6.54",
            "currency": "USD"
          },
          "date_time": "2025-02-28T00:00:00Z",
          "posted_date_time": "2025-02-28T00:00:00Z",
          "status": "booked",
          "suggested_description": "Dunkin'",
          "suggested_logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg",
          "enrichments": {
            "merchant": {
              "id": "ba8ef908-b624-4116-8b26-571e48d1bf4c",
              "slug": "dunkin",
              "display_name": "Dunkin'",
              "logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg",
              "website": "https://www.dunkindonuts.com",
              "tokens": [
                {
                  "confidence": "1.00",
                  "value": "DUNKIN DONUTS COFFEE"
                }
              ]
            },
            "categories": {
              "l1": {
                "slug": "food_and_drink",
                "confidence": "0.98"
              },
              "l2": {
                "slug": "coffee",
                "confidence": "0.97"
              }
            },
            "regularity": {
              "frequency": "biweekly",
              "predicted_date_times": [
                "2025-03-14T00:00:00Z",
                "2025-03-28T00:00:00Z",
                "2025-04-11T00:00:00Z",
                "2025-04-25T00:00:00Z",
                "2025-05-09T00:00:00Z",
                "2025-05-23T00:00:00Z",
                "2025-06-06T00:00:00Z",
                "2025-06-20T00:00:00Z"
              ],
              "group_label": "3e1b2ea4df1579fe9dcda6cf6b032492d8551e78404d023ca3d57ca8b1ae2159-3"
            },
            "location": {
              "address": {
                "city": "New York",
                "region": "NY",
                "country": "US"
              },
              "geolocation": {
                "longitude": -73.9872777778,
                "latitude": 40.6919444444
              }
            }
          },
          "tags": [
            "regular-transaction"
          ]
        }
      }
    ],
    "suggested_searches": [
      {
        "filter": {
          "type": "merchant_name",
          "value": "Dunkin'",
          "logo": "https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png"
        },
        "url": "/search/beta/transactions?merchant_name=Dunkin'"
      },
      {
        "filter": {
          "type": "category_l2",
          "value": "coffee",
          "logo": "https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png"
        },
        "url": "/search/beta/transactions?category_l2=coffee"
      }
    ],
    "insight": {
      "url": "/search/beta/transactions/8a567b41-1b61-4f8f-a1ea-8fcb10d08d9f/insight",
      "url_delay": 1500
    }
  },
  "metadata": {
    "query": {
      "user_input": "Dunki",
      "from": "2025-01-01T00:00:00Z",
      "to": "2025-02-01T00:00:00Z"
    },
    "next_page_token": "eyJoZWxsbyI6ICJ3b3JsZCJ9Cg==",
    "results": 2,
    "expires_in": 60
  }
}
```
```Text cURL Request
curl --request GET \
     --url 'https://api-sandbox.thisisbud.com/search/beta/transactions?user_input=coffee' \
     --header 'Accept: application/bud-transaction-v3+json' \
     --header 'Authorization: Bearer <oauth_token>' \
     --header 'X-Client-Id: <bud_client_id> \
     --header 'X-Customer-Id: <bud_customer_id> \
     --header 'X-Timezone: US/Pacific'
```

Contained within the response is; a list of transactions , `suggested_searches` and a url for the associated insight.

As previously mentioned the transactions returned will follow the same format as our [GET financial/v2/transactions](https://docs-us.thisisbud.com/reference/v2_transactions_get-1) response and contain all of the enrichment information that you would expect to see.

`suggested_searches` are recommendations from Bud of subsequent searches that your customer may want to make based on their initial search and the results, for example, if a customer initially searched for `car` we may suggest subsequent searches such as `car_payment` or `vehicle_insurance` to help the customer find what they're looking for. Each `suggested_search` will also contain a `type` that corresponds to our query parameters or equally you can follow the `url` provided for the subsequent search.

<Image align="center" alt="Example of `suggested_searches`" border={false} caption="Example of `suggested_searches`" src="https://files.readme.io/08dfa58fc4e1da5e8bf90731e53a58f4d1f48aead61a35dc23589dfe82ed2f69-Screenshot_2025-08-04_at_17.50.04.png" />

## Providing insights

With Intelligent Search you can also provide insights to your customers about the queries that they're searching for. You can do this by either following `url` returned in the `insight` object of the [search](https://docs-us.thisisbud.com/reference/search_beta_transactions_get) response or by calling [GET search/beta/transactions/\{search\_id}insight](https://docs-us.thisisbud.com/reference/search_beta_transactions_insight_get) with the `search_id`

When calling this endpoint you may retrieve a `status` of `pending`, if this happens, it means that we're still generating the insight, you can use the `Retry-After` header in the response to poll until the insight is generated.

<Callout icon="📘" theme="info">
  Please note, it is possible for a search to not have a related insight, in this case you will receive a `status` of `completed` but the text field will be empty.
</Callout>

An example of a request and a successful `200` response with a `status` of `completed` can be seen below.

```Text json Response
{
  "operation_id": "search_beta_transactions_insight_get",
  "data": {
    "id": "234029b1-37ee-4942-b56d-5588f293f571",
    "status": "completed",
    "content": {
      "text": "You have spent $20 at Dunkin', this is up 50% of your coffee spend....",
      "matched_searches": [
        {
          "filter": {
            "type": "merchant",
            "value": "Dunkin'",
            "logo": "https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png"
          },
          "url": "/search/beta/transactions?merchant=Dunkin'",
          "text_positions": [
            {
              "start": 22,
              "end": 59
            }
          ]
        },
        {
          "filter": {
            "type": "category_l2",
            "value": "coffee",
            "logo": "https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png"
          },
          "url": "/search/beta/transactions?category_l2=coffee",
          "text_positions": [
            {
              "start": 64,
              "end": 70
            }
          ]
        }
      ]
    },
    "transactions": {
      "url": "/search/beta/transactions/234029b1-37ee-4942-b56d-5588f293f571/insight/transactions",
      "results": 10,
      "merchants": [
        {
          "display_name": "Dunkin'",
          "logo": "https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png"
        }
      ]
    }
  },
  "metadata": {
    "query": {
      "user_input": "Dunki",
      "from": "2025-01-01T00:00:00Z",
      "to": "2025-02-01T00:00:00Z"
    },
    "expires_in": 60
  }
}
```
```Text cURL Request
curl --request GET \
     --url https://api-sandbox.thisisbud.com/search/beta/transactions/<search_id>/insight \
     --header 'Accept: application/bud-transaction-v3+json' \
     --header 'Authorization: Bearer <oauth_token>' \
     --header 'X-Client-Id: <bud_client_id> \
		 --header 'X-Customer-Id: <bud_customer_id> \
     --header 'X-Timezone: US/Pacific'
```

The insight itself can be found in the `text` field, in addition to this we will also provide any `matched_searches` these are merchants or categories that are mentioned in the insight as well as the `text_position` and `url`, this provides you with the option to stylise these words differently and create links to subsequent searches if you would like to. An example of this can be seen in the image below.

<Image align="center" alt="Example of `matched_searches`" border={false} caption="Example of `matched_searches`" src="https://files.readme.io/05aad53fc63af7b5b4a2523abf46c8dc2eff2d75c7f634bdfd2923889e9469e9-Screenshot_2025-08-04_at_17.14.57.png" />

### Transactions linked to an insight

Another part of the Insight response is the transactions object, this provides you with a `url` to retrieve the transactions that are used to calculate the insight as well as the number of transactions and any merchants and associated logo's for those transactions. These fields allows you to have an element of explainability with your customers and allows them to naturally explore their transactions and dive deeper should they wish.

In addition to the url in the Insights endpoint you can also call [GET search/beta/transactions/\{search\_id}/insight/transactions](https://docs-us.thisisbud.com/reference/search_beta_transactions_insight_transactions_get) in order to retrieve the same response.

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

```Text json Response
{
  "operation_id": "search_beta_transactions_insight_transactions_get",
  "data": {
    "id": "8a567b41-1b61-4f8f-a1ea-8fcb10d08d9f",
    "results": [
      {
        "matches": [
          {
            "type": "merchant_name",
            "content": "Dunkin'"
          },
          {
            "type": "category_l2",
            "content": "coffee"
          }
        ],
        "transaction": {
          "transaction_id": "378",
          "account_id": "5ce0749e-551c-4693-87f8-400d2551fdd1",
          "provider": "Chase",
          "description": "DUNKIN DONUTS COFFEE BROOKLYN NEW YORK",
          "credit_debit_indicator": "debit",
          "amount": {
            "value": "8.87",
            "currency": "USD"
          },
          "date_time": "2025-03-02T00:00:00Z",
          "posted_date_time": "2025-03-02T00:00:00Z",
          "status": "booked",
          "suggested_description": "Dunkin'",
          "suggested_logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg",
          "enrichments": {
            "merchant": {
              "id": "ba8ef908-b624-4116-8b26-571e48d1bf4c",
              "slug": "dunkin",
              "display_name": "Dunkin'",
              "logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg",
              "website": "https://www.dunkindonuts.com",
              "tokens": [
                {
                  "confidence": "1.00",
                  "value": "DUNKIN DONUTS COFFEE"
                }
              ]
            },
            "categories": {
              "l1": {
                "slug": "food_and_drink",
                "confidence": "0.98"
              },
              "l2": {
                "slug": "coffee",
                "confidence": "0.96"
              }
            },
            "regularity": {
              "frequency": "biweekly",
              "predicted_date_times": [
                "2025-03-17T00:00:00Z",
                "2025-03-31T00:00:00Z",
                "2025-04-14T00:00:00Z",
                "2025-04-28T00:00:00Z",
                "2025-05-12T00:00:00Z",
                "2025-05-27T00:00:00Z",
                "2025-06-09T00:00:00Z",
                "2025-06-23T00:00:00Z"
              ],
              "group_label": "3e1b2ea4df1579fe9dcda6cf6b032492d8551e78404d023ca3d57ca8b1ae2159-4"
            },
            "location": {
              "address": {
                "city": "New York",
                "region": "NY",
                "country": "US"
              },
              "geolocation": {
                "longitude": -73.9872777778,
                "latitude": 40.6919444444
              }
            }
          },
          "tags": [
            "regular-transaction"
          ]
        }
      },
      {
        "matches": [
          {
            "type": "merchant_name",
            "content": "Dunkin'"
          },
          {
            "type": "category_l2",
            "content": "coffee"
          }
        ],
        "transaction": {
          "transaction_id": "377",
          "account_id": "5ce0749e-551c-4693-87f8-400d2551fdd1",
          "provider": "Chase",
          "description": "DUNKIN DONUTS COFFEE BROOKLYN NEW YORK",
          "credit_debit_indicator": "debit",
          "amount": {
            "value": "6.54",
            "currency": "USD"
          },
          "date_time": "2025-02-28T00:00:00Z",
          "posted_date_time": "2025-02-28T00:00:00Z",
          "status": "booked",
          "suggested_description": "Dunkin'",
          "suggested_logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg",
          "enrichments": {
            "merchant": {
              "id": "ba8ef908-b624-4116-8b26-571e48d1bf4c",
              "slug": "dunkin",
              "display_name": "Dunkin'",
              "logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg",
              "website": "https://www.dunkindonuts.com",
              "tokens": [
                {
                  "confidence": "1.00",
                  "value": "DUNKIN DONUTS COFFEE"
                }
              ]
            },
            "categories": {
              "l1": {
                "slug": "food_and_drink",
                "confidence": "0.98"
              },
              "l2": {
                "slug": "coffee",
                "confidence": "0.97"
              }
            },
            "regularity": {
              "frequency": "biweekly",
              "predicted_date_times": [
                "2025-03-14T00:00:00Z",
                "2025-03-28T00:00:00Z",
                "2025-04-11T00:00:00Z",
                "2025-04-25T00:00:00Z",
                "2025-05-09T00:00:00Z",
                "2025-05-23T00:00:00Z",
                "2025-06-06T00:00:00Z",
                "2025-06-20T00:00:00Z"
              ],
              "group_label": "3e1b2ea4df1579fe9dcda6cf6b032492d8551e78404d023ca3d57ca8b1ae2159-3"
            },
            "location": {
              "address": {
                "city": "New York",
                "region": "NY",
                "country": "US"
              },
              "geolocation": {
                "longitude": -73.9872777778,
                "latitude": 40.6919444444
              }
            }
          },
          "tags": [
            "regular-transaction"
          ]
        }
      }
    ]
  },
  "metadata": {
    "query": {
      "user_input": "Dunki",
      "from": "2025-01-01T00:00:00Z",
      "to": "2025-02-01T00:00:00Z"
    },
    "next_page_token": "eyJoZWxsbyI6ICJ3b3JsZCJ9Cg==",
    "expires_in": 60
  }
}
```
```Text cURL Request
curl --request GET \
     --url https://api-sandbox.thisisbud.com/search/beta/transactions/<search_id>/insight/transactions \
     --header application/bud-transaction-v3+json' \
     --header 'Authorization: Bearer <oauth_token>' \
     --header 'X-Client-Id: <bud_client_id> \
     --header 'X-Customer-Id: <bud_customer_id> \
     --header 'X-Timezone: US/Pacific'
```

The response contains all of the transactions associated with the insight in the same format as the original [search](https://docs-us.thisisbud.com/reference/search_beta_transactions_get) endpoint as well as [GET financial/v2/transactions](https://docs-us.thisisbud.com/reference/v2_transactions_get-1).

<br />

***

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via <a href="https://support.thisisbud.com/hc/en-gb/requests/new" target="_blank">a support request</a> or check our <a href="https://support.thisisbud.com" target="_blank">FAQs</a>.<br /><br />