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.
Displaying and searching transactions
Calling GET search/beta/transactions 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, 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 starbwill 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.
{
"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
}
}
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 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.
Example of suggested_searches
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 response or by calling GET search/beta/transactions/{search_id}insight 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.
Please note, it is possible for a search to not have a related insight, in this case you will receive a
statusofcompletedbut the text field will be empty.
An example of a request and a successful 200 response with a status of completed can be seen below.
{
"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
}
}
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.
Example of matched_searches
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 in order to retrieve the same response.
An example of a request and a successful 200 response can be seen below.
{
"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
}
}
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 endpoint as well as GET financial/v2/transactions.
If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.
Updated 6 days ago