Alternative Data Sharing Methods

While our RESTful APIs are the most common way to integrate with Bud, we know that every client has unique needs. That’s why we provide several simple, low-effort options for you to securely share your customer data with us.

One of the most popular alternatives is to export your data and upload it in Parquet or CSV format to a secure SFTP account we provide. We’re also flexible and can support other data formats and entry points, including Kafka topics or read-only access to a storage location you specify.

The data to share with Bud

Regardless of how you share your data, certain products need specific data points from you to work as they should. You'll find a list of the entities you can ingest below, along with the required attributes for our products to function.

Please note that you don't have to use the exact attribute names listed in this document. We can map our ingestion process to match the naming convention you use.

Transactions

Most of the use cases require you to share Transactions with Bud. Here you can find the list of attributes that are required to be included (indicated with an *), and attributes that help us improving the predictions and other products:

AttributeDescription
User ID *User identifier

eg: user-123
Account ID *The account identifier that the transaction belongs to.

eg: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
ProviderThe name of the financial institution the transaction has come from. This can be ignored if you already provide this information in the Account entity (specified below).

eg: Bank Of America
Transaction IDUnique, immutable transaction identifier. This can be of any format (not necessarily UUID). Bud can also generate this if not provided.

eg: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
Description *Free text string providing details on the transaction itself

eg: dunkin purchase 06/04 urbana oh
Posted Date Time *Date the assets involved in the transaction transferred compliant with RFC3339, including the timezone. For credits this is the date that the asset becomes available, for debits this is the date that the asset ceased to be available.

eg: 2023-10-27T09:30:00+01:00
Transaction Date TimeThe date detailing when the transaction occurred, compliant with RFC3339, including the timezone.

eg: 2023-10-27T09:30:00+01:00
StatusThe status of the transaction. If not provided, the default value is booked, and we assume you won’t share pending transactions with Bud.

eg: booked, pending
Amount *The value of the monetary amount. The value is formatted with the number of decimal places for the respective currency.

A positive amount is a credit entry and a negative a debit entry.

Note: for this and all the other Amount attributes in this doc, a common alternative is to share the amount value as always positive and include an additional Credit Debit attribute to the entity. This is an accepted alternative when sharing data with Bud.

eg: 10.98
Currency *The three-letter ISO currency code of the monetary amount.

eg: USD
Merchant Category CodeA Merchant Category Code (MCC) is a four-digit number listed in ISO 18245.

An MCC is used to classify a business by the types of goods or services it provides.

eg: 0018
Merchant NameThe merchant name as identified by you

eg: Amazon
Transactions Type CodeThe code associated with a transaction type.

eg: DEB
Transactions Type DescriptionA human-readable description of the transaction type code

eg: Contactless POS

Accounts

To ensure we can effectively analyse the Customers' transactions, we often need information regarding the accounts they belong to.

When you share with Bud the Account entity, these are the required attributes we expect to properly ingest your data:

AttributeDescription
User ID *User identifier. Note: this needs to match the Account ID values shared for the other entities (Transactions, Balances, ….).

eg: user-123
Account ID *The account identifier that the transaction belongs to. Note: this needs to match the Account ID values shared for the other entities (Transactions, Balances, ….).

eg: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
Provider *The name of the financial institution the transaction has come from.

eg: Bank Of America
Type *The type of the account.

eg: CheckingAccount
Usage TypeThe intended usage of the account. When not provided, all accounts are assumed to be personal.

eg: personal, business
CurrencyThe three-letter ISO currency code of the monetary amount. If not provided this is calculated from one of the other data points (balances or transactions).

eg: USD
Holder NamesA list of Account Holder Names. Based on the format used to share the data with Bud, this can be a string | separated, or an list of elements.

eg: John Doh|Jane D.
Account NumberThe account number. This can also be an IBAN or other identifier.

eg: 00123456789
NicknameA human-readable description that helps identifying the account when included in a list.

eg: Checking Personal 789
StatusThis determines whenever an account is open or closed.

When an account you ingested in the past has now been closed, you can share a new record with us with the related status and we will stop considering this account from now on. When sending this information, please, ensure to also share with us the Closing Date Time.

When this is not provided, we assume the account is still open.

eg: open
Closing Date TimeDate and time when the account was closed, RFC3339, including the timezone. Please, ensure to include the time as well as the date.

This is mandatory when sharing a closed account.

eg: 2023-10-27T09:30:00+01:00

Balances

The Balance entity is required for us to be able to calculate those insights that are based on the Balance movement for your customers.

It’s important to note that if you only share with us booked transactions, we expect to receive a balance that includes only booked transactions (in order for us to be able to properly calculate insights based on the combination of the two entities).

It’s not important to have the accounts and balances entities separated as described here, the two information can be combined.

These are the attributes used by Bud when it comes to balances:

AttributeDescription
User ID *User identifier. Note: this needs to match the Account ID values shared for the other entities (Transactions, Accounts, ….)

eg: user-123
Account ID *The account identifier that the transaction belongs to. Note: this needs to match the Account ID values shared for the other entities (Transactions, Accounts, ….).

eg: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
TypeThe balance type. This can be omitted if you will always share the same type with Bud (as long as this is communicated with us).

eg: closing_booked
Date Time *Date and time when the balance was calculated, RFC3339, including the timezone. Please, ensure to include the time as well as the date.

eg: 2023-10-27T09:30:00+01:00
Amount *The value of the monetary amount. The value is formatted with the number of decimal places for the respective currency.

A positive amount is a credit entry and a negative a debit entry.

eg: 10.90
Currency *The three-letter ISO currency code of the monetary amount.

eg: USD
Credit Line AmountThe latest lines of credit available to the account. This is typically a representation of the overdraft or credit limits.
The value is formatted with the number of decimal places for the respective currency.

eg: 3000.00

Additional User’s Details

In many cases, especially when using our Drive product, you might also want to share additional data with Bud, including customer’s details (like email, phone number, name, etc…).

We are equipped to receive and store this data when required, and you can define the list of attributes to share as it best suites you.

Combine the entities when using the sFTP ingestion method

When you share your data with Bud through an sFTP (this is just one of the options), the name of the files shared is also important as it helps us to understand when all the entities have been shared in the folder and when we are ready to start the ingestion process.

When naming the files, please, ensure to include a grouping identifier: an example can be the date and time when the files where shared.

For example, if you use the sFTP method to ingest transactions, accounts, and balances we would expect to find in the folder the following files:

20250826_transactions.parquet
20250826_accounts.parquet
20250826_balances.parquet

Verifying Data Ingestion

We provide different ways for you to confirm that your data has been successfully ingested. Your feedback loop will depend on the method you choose for data sharing.

If you share data via SFTP, we'll generate and place a new report file on the server once the ingestion is finished. This report contains a detailed summary of the data that was ingested.

For a more real-time approach, you can subscribe to our callback URLs. These allow you to receive notifications for various events, keeping you informed about the status of your data ingestion.




If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.