Synchronous Transaction Enrichment End-to-End Walkthrough
Bud's transaction enrichment allows you to synchronously enrich transactions with categories, merchants and locations and recevie the enriched transactions within a single API. Below we'll explain the full process of getting set up with the Bud platform and enriching your first transactions.
Getting started
Introduction to Bud's Console
Once you've selected an enrichment package you will receive an email linking you to the Bud Console and granting you production access. If you have an existing account with the Bud Console, this will be promoted to production, if you don't have an existing account then the email used as part of the purchase will have an account created for it.
The Bud Console can be used for;
- Creating and managing different Projects (aka API keys) that can be used to pull dummy data into the Bud platform to help you start integrating, testing, and building against Bud’s API services.
- Inviting teammates and collaborating together. No more sharing API keys and log in credentials, head to the Team tab in the console and input the email addresses of all your teammates who need to engage with Bud.
Creating API Credentials
The Bud Console allows you to manage your access to Bud's API services through the creation of different Projects. Each Project will have it's own set of API Keys.
On the creation of a new project, you will be provided with a Client ID and Client secret. Please store your Client secret securely as you will be unable to retrieve it again from Bud.
Projects (aka API keys/credentials) are specific to the relevant Bud environment in which you are enrolled (e.g. Bud's Sandbox environment and Bud's Production environment). You can navigate between these environments via a drop-down menu at the top of the right-hand side navigation bar
Authenticate to Bud's API Services
Having acquired a set of API credentials from the Bud console, the next step is to use them to obtain valid access and refresh tokens.
Authentication to Bud’s API services is made via OAuth2 protocol, whereby your API Credentials are used in exchange for a valid access_token and refresh_token. The access_token is valid for up to one hour, (although can expire early), after which you will then have to use the refresh_token or your API credentials in order to obtain a new one.
Access tokens will last up to one hour, but they can also expire before that period of time has elapsed. It is important your application is resilient to handle token expiration.
We recommend that you implement logic such that if you ever receive a 401 or 403 on the Bud Platform, you attempt to retrieve a new access token before then retrying your API call as this likely indicates that the access token you are using has expired.
Access and refresh tokens are obtained via the POST /v1/oauth/token endpoint. Specify the grant_type as client_credentials within the request body and use HTTP Basic authentication within the request header. The basic authentication header is a base64 encoding of your API credentials, i.e. base64({client_id}:{client_secret}).
Example Access request (curl):
curl --basic --user {{client_id}}:{{client_secret}}
-X POST <https://api-sandbox.thisisbud.com/v1/oauth/token>
-H 'Content-Type: application/x-www-form-urlencoded'
-d grant_type=client_credentials
Successful response:
Successful response:
{
"operation_id": "oauth_token_post",
"data": {
"access_token": "dd0c17e3fd6d2ce94aa091257a3ea393b4f9b5cf3d3e998f07dc9826da86ff15",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "fac32cca7559d9f6e8f1dfe9a99c71fa1dcfeb482bedf287d7934d2667ae54b3"
}
}
Enriching Transactions
Now that you're set up in the Bud Console and have a valid access_token you can start ingesting transactions via the first party ingester.
First party ingestion is the term used to describe the process of sending raw transaction data to the Bud Platform for them to be enriched and returned, you can do this via the POST /v2/ingest/transactions endpoint.
Headers
The Ingest Transactions endpoint has several headers available when calling the endpoint;
| Header | Description |
|---|---|
| X-Client-Id | The corresponding ID to the project that you created earlier, the ID can be found on the project page of the Bud Console |
| Content-Type | Defines the content schema for the transactions supplied in the request, by default we expect clients to use application/bud-transaction-v3+json however, there are also schemas available for third party aggregators such as Plaid and Finicity |
| X-No-Customer | This header will need to be set to true |
Example Request
The example request below shows the attributes you should send in the request to the Ingest Transactions endpoint:
[
{
"customer_id": "",
"transactions":
[
{
"transaction_id": "dZyaKRwkKZULmmkd0wkLc0wLKo5zd123123V4",
"description": "Macbook Pro 16\" 512GB",
"account_id": "99473c28-21cf-4a9a-b79e-fd643dd7a4bc",
"date_time": "2023-11-08T02:07:14Z",
"amount": "-2300.00",
"currency": "USD",
"country_code": "US",
"merchant_category_code": "1053",
"transaction_type": "DEB",
"client_attributes": {
"user_id": "ID-12221"
}
},
{
"transaction_id": "dZyaKRwkKZULmmkd0wkLc0wLKo5zd123123V5",
"description": "Starbucks",
"account_id": "99473c28-21cf-4a9a-b79e-fd643dd7a4bc",
"date_time": "2023-11-02T02:07:14Z",
"amount": "-23.00",
"currency": "USD"
"country_code": "US",
"merchant_category_code": "1001",
"transaction_type": "DEB",
"client_attributes": {
"user_id": "ID-12222"
}
}
]
}
]
The table below shows the recommended and maximum number of transactions that can be submitted per customer within a single ingest transactions request. Exceeding the hard limit will result in a 400 error response.
| Recommended | Hard Limit |
|---|---|
| 500 | 1000 |
Example Response
If the ingest transactions request has been successful Bud returns a 200 response status code and you can expect to see the enriched transactions with categories, merchants, and locations in the response as shown below.
{
"operation_id": "v2_ingest_transactions_post",
"data": [
{
"customer_id": "",
"enriched_transactions": [
{
"transaction_id": "another_transaction_id",
"account_id": "another_account_id",
"description": "paypal* specialty coffee NY US",
"credit_debit_indicator": "debit",
"status": "pending",
"suggested_description": "Specialty Coffee Supplier Ltd.",
"suggested_logo": "http://url/specialty_coffee_supplier_logo.jpeg",
"transaction_type": {
"bud_code": "DEB",
"description": "PayPal"
},
"amount": {
"value": "10.99",
"currency": "USD"
},
"date_time": "2022-05-28T10:00:00Z",
"tags": [
"online"
],
"enrichments": {
"categories": {
"l1": {
"slug": "food_and_drink",
"confidence": "0.99"
},
"l2": {
"slug": "coffee",
"confidence": "0.98"
}
},
"merchant": {
"id": "01cc2d49-6144-46f1-9414-67c99b139a95",
"slug": "specialty_coffee",
"display_name": "Specialty Coffee Supplier Ltd.",
"logo": "http://url/specialty_coffee_supplier_logo.jpeg",
"tokens": [
{
"value": "speciality coffee",
"confidence": "0.98"
}
]
},
"processor": {
"id": "18f63293-0217-4520-bbf0-071dca7a9d04",
"slug": "paypal",
"display_name": "PayPal",
"logo": "http://url/paypal_logo.jpeg",
"tokens": [
{
"value": "paypal",
"confidence": "0.92"
}
]
},
"transaction_types": [
"card",
"debit"
]
}
},
{
"transaction_id": "a2294cebb45d2a6e0cfc70d270988d8c",
"account_id": "37c633a71237b9a8282e09587109668e",
"description": "starbucks 1500 broadway ny ny 10036",
"credit_debit_indicator": "debit",
"status": "booked",
"suggested_description": "Starbucks",
"suggested_logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v2/starbucks.jpeg",
"transaction_type": {
"bud_code": "DEB",
"description": "Debit card transaction"
},
"amount": {
"value": "3.29",
"currency": "USD"
},
"date_time": "2022-05-26T10:00:00Z",
"merchant_category_code": "5814",
"enrichments": {
"categories": {
"l1": {
"slug": "food_and_drink",
"confidence": "0.99"
},
"l2": {
"slug": "coffee",
"confidence": "0.99"
}
},
"merchant": {
"id": "4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf",
"slug": "starbucks",
"display_name": "Starbucks",
"logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v1/starbucks.jpeg",
"tokens": [
{
"value": "starbucks",
"confidence": "1.00"
}
]
},
"location": {
"address": {
"address_lines": [
"1500 Broadway",
"New York",
"NY",
"10036"
],
"street_address": "1500 Broadway",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country": "US"
},
"geolocation": {
"longitude": 40.756635,
"latitude": -73.985983
},
"tokens": [
"1500 broadway",
"ny"
]
}
}
},
{
"transaction_id": "cfb6dd1f4c73e1fc36aac756e12644d7",
"account_id": "37c633a71237b9a8282e09587109668e",
"description": "JOHN SMITH RENT SHARE",
"credit_debit_indicator": "debit",
"amount": {
"value": "375.00",
"currency": "USD"
},
"date_time": "2022-05-30T00:00:00Z",
"status": "booked",
"suggested_description": "JOHN SMITH RENT SHARE",
"transaction_type": {
"bud_code": "BAT",
"description": "Bank Transfer"
},
"enrichments": {
"categories": {
"l1": {
"slug": "mortgage_and_rent",
"confidence": "0.98"
},
"l2": {
"slug": "rent",
"confidence": "0.98"
}
},
"names": [
"john smith"
]
}
}
]
}
],
"metadata": {
"task_id": ""
}
Error Handling
If the request has failed you can expect to receive a 400 response containing an error code_id and message. The exact error should be displayed within the errors object. In the example below, you can see the root cause of this error is the amount has not been validated and we're missing the description and account_id.
{
"operation_id": "v2_ingest_transactions_post",
"code_id": "failed_validation",
"message": "validation failure(s) in request payload",
"errors": {
"missing_fields": {
"transactions[0]": [
"description",
"account_id"
]
},
"invalid_fields": {
"transactions[0]": [
"amount"
]
}
}
}
In the case that you receive an error it is important to use the errors object to understand why the request is failing and to update any fields before resending the request.
Understanding Bud's enrichments
Each enriched transaction is represented by two main sections; the main list of attributes and the individual enrichments.
Here you can see an example of the main attribute set of a transaction.
"transaction_id": "a2294cebb45d2a6e0cfc70d270988d8c",
"account_id": "37c633a71237b9a8282e09587109668e",
"description": "starbucks 1500 broadway ny ny 10036",
"credit_debit_indicator": "debit",
"status": "booked",
"suggested_description": "Starbucks",
"suggested_logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v2/starbucks.jpeg",
"transaction_type": {
"bud_code": "DEB",
"description": "Debit card transaction"
The majority of these fields such as transaction_id, account_id, description etc. will be populated as part of the original request to Bud, with two exceptions.
The suggested_description and suggested_logo fields are derived from the enrichments that have been run against the transaction. The purpose of these fields is to inform Clients of how Bud suggests transactions should be shown to customers to give the best possible experience. They strike a balance between visual cleanliness and comprehensibility. The suggested_description is a required field and will always be populated, whereas the suggested_logo is optional and will not be present in the response if we haven't found a merchant or processor match in our database. Therefore, clients are advised to implement logic to handle dealing with transactions where Bud is unable to provide a logo.
Please note whenever displaying a transaction to a customer, Bud would always advise Clients to let a customer 'click in' to the transaction in order to be able to see more information including the full transaction description.
The second part of the transaction is the enrichments as shown below
"enrichments": {
"categories": {
"l1": {
"slug": "food_and_drink",
"confidence": "0.99"
},
"l2": {
"slug": "coffee",
"confidence": "0.99"
}
},
"merchant": {
"id": "4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf",
"slug": "starbucks",
"display_name": "Starbucks",
"logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v1/starbucks.jpeg",
"tokens": [
{
"value": "starbucks",
"confidence": "1.00"
}
]
},
"location": {
"address": {
"address_lines": [
"1500 Broadway",
"New York",
"NY",
"10036"
],
"street_address": "1500 Broadway",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country": "US"
},
"geolocation": {
"longitude": 40.756635,
"latitude": -73.985983
},
"tokens": [
"1500 broadway",
"ny"
]
}
Categories
"categories": {
"l1": {
"slug": "food_and_drink",
"confidence": "0.99"
},
"l2": {
"slug": "coffee",
"confidence": "0.99"
}
},
Categories associated with a transaction, as generated by Bud's artificial intelligence models. Currently, two levels of category are supported, with l1 being the higher level category and l2 being more refined and specific. Typically we would expect l1s to be of sufficient detail to present back to customers in personal finance management apps and l2s to be used for more detailed analysis such as affordability analysis and monitoring.
Each category level is represented by a slug that can be used to uniquely identify a category and a confidence that is a value between 0.50 and 1.00 indicating the level of confidence behind the category match.
Merchant
"merchant": {
"id": "4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf",
"slug": "starbucks",
"display_name": "Starbucks",
"logo": "https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v1/starbucks.jpeg",
"tokens": [
{
"value": "starbucks",
"confidence": "1.00"
}
]
},
Merchant enrichment associated with a transaction, as generated using a combination of Bud's artificial intelligence models and our proprietary database of known merchants.
The logo and website information are not always present, they are populated only when the recognized merchant is part of our database. This happens for the majority of the merchants recognized by our models, and we constantly improve the data set to ensure the best possible coverage.
Processor
"processor": {
"id": "18f63293-0217-4520-bbf0-071dca7a9d04",
"slug": "paypal",
"display_name": "PayPal",
"logo": "http://url/paypal_logo.jpeg",
"tokens": [
{
"value": "paypal",
"confidence": "0.92"
}
]
},
Processor enrichment associated with a transaction, as generated using a combination of Bud's artificial intelligence models and a database of known payment processors.
The logo and website information are not always present, they are populated only when the recognized processor is part of our database. This happens for the majority of the processors recognized by our models, and we constantly improve the data set to ensure the best possible coverage.
Location
"location": {
"address": {
"address_lines": [
"1500 Broadway",
"New York",
"NY",
"10036"
],
"street_address": "1500 Broadway",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country": "US"
},
"geolocation": {
"longitude": 40.756635,
"latitude": -73.985983
},
"tokens": [
"1500 broadway",
"ny"
]
}
The location enrichment represents the place where the transaction took place. Its definition includes a list of attributes that define the location as a human-readable address, and its geolocation representation that allows Clients to represent transactions on a map.
For online transactions such as with Amazon or a Netflix subscription, we will add an online tag to the transaction so that you know there is no physical address associated with the transaction.
Names
"names": [
"john smith"
]
A list of possible names of people as found in the transaction description. This is often present when the transaction represents an exchange of money between individuals.
Tokens
In many of Bud's enrichment entities we include an attribute name tokens that represents a list of strings correlated to the enrichment itself. This can often be used as a support to represent the enrichment result to the end user or to internally classify it.
Tags
A list of potential tags associated with the transaction after contextual enrichment, which can be used for filtering.
| Value | Description |
|---|---|
benefit | A government/non-profit benefit transaction |
debt-collection | A transaction associated with a known debt-collector |
loan | A transaction associated with a loan |
income | A transaction associated with income |
pending | A transaction that has not been booked |
regular-transaction | A transaction predicted to occur with a regular frequency |
subscription | A transaction associated with a subscription service |
online | A transaction associated with an online merchant |
bill | A transaction associated with a bill payment |
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 about 1 month ago