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:
Attribute | Description |
---|---|
User ID * | User identifier eg: user-123 |
Account ID * | The account identifier that the transaction belongs to. eg: 4cef424c-1d7f-4cab-8be2-aee7e1774a00 |
Provider | The 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 ID | Unique, 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 Time | The date detailing when the transaction occurred, compliant with RFC3339, including the timezone. eg: 2023-10-27T09:30:00+01:00 |
Status | The 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 Code | A 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 Name | The merchant name as identified by you eg: Amazon |
Transactions Type Code | The code associated with a transaction type. eg: DEB |
Transactions Type Description | A 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:
Attribute | Description |
---|---|
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 Type | The intended usage of the account. When not provided, all accounts are assumed to be personal. eg: personal , business |
Currency | The 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 Names | A 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 Number | The account number. This can also be an IBAN or other identifier. eg: 00123456789 |
Nickname | A human-readable description that helps identifying the account when included in a list. eg: Checking Personal 789 |
Status | This 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 Time | Date 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:
Attribute | Description |
---|---|
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 |
Type | The 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 Amount | The 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.
Updated about 9 hours ago