Setup First Party Ingestion
How to successfully ingest customer transactions into the Bud Platform.
What is First Party Ingestion?
First party ingestion is the term used to describe the process of sending raw transaction and account data to the Bud Platform in order for us to enrich this data. Once the data is in the Bud Platform and enriched, you can then make API calls to your contracted Bud Solution (Assess, Engage, Drive).
Below, we’ll provide steps and recommendations to help you successfully ingest customer transactions into the Bud Platform. In addition to reading this guide, please also refer to the API documentation for Ingesting Transactions.
Prerequisites
Before starting you'll need to:
- Create a set of API credentials - you can read our guide on how to do this here
- Create a customer - you can find our guide on customers at Bud here
Synchronous vs Asynchronous Mode
You will need to decide whether to integrate this endpoint in either synchronous or asynchronous mode.
The main difference is that when you integrate this endpoint in synchronous mode, the response body contains the ingested transactions partially enriched with categorization and merchants information. This gives you the ability to get the main enrichments back while we process the full set of enrichments in the background. In asynchronous mode we don't return the partially enriched categorization and merchants information in the response. Instead we simply return a task_id and complete all enrichments in the background asynchronously.
You can switch between synchronous and asynchronous mode by including the X-Disable-Synchronous field within the HTTP header.
If X-Disable-Synchronous is provided as false or this field is not included in the HTTP header, the ingested transactions will be processed in synchronous mode.
If X-Disable-Synchronous is provided as true, the ingested transactions will be processed in asynchronous mode.
Bud enriches transactions from the last two years, so please don’t ingest any transactions older than this.
Ingest Transactions - Example Request
The example request below shows the fields you should send in the request to the Ingest Transaction endpoints. For further details please refer to the Ingest Transactions API Document.
[
{
"customer_id": "f4c8dcf9-7e87-4bdd-8f60-acbcfb6b58ce",
"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"
},
{
"transaction_id": "dZyaKRwkKZULmmkd0wkLc0wLKo5zd123123V5",
"description": "Starbucks",
"account_id": "99473c28-21cf-4a9a-b79e-fd643dd7a4bc",
"date_time": "2023-11-02T02:07:14Z",
"amount": "-23.00",
"currency": "USD"
}
],
"transaction_windows":
[
{
"account_id": "99473c28-21cf-4a9a-b79e-fd643dd7a4bc",
"start": "2023-11-01T23:00:00Z",
"end": "2023-11-10T23:00:00Z"
}
]
}
]
Ingest Transactions Limits
The table below shows the recommended and maximum number of transactions that can be submitted per customer within a single ingest transaction’s request. Exceeding the hard limit will result in an 400 error response.
| Recommended | Hard Limit |
|---|---|
| 500 | 1000 |
Bud enriches transactions from the last two years, so please don’t ingest any transactions older than this.
Synchronous Processing Mode - Example Response
If the ingest transactions request has been successful you can expect to see the partially enriched transactions and a task_id in the response as shown below.
{
"operation_id": "v2_ingest_transactions_post",
"data": [
{
"customer_id": "f4c8dcf9-7e87-4bdd-8f60-acbcfb6b58ce",
"enriched_transactions": [
{
"transaction_id": "dZyaKRwkKZULmmkd0wkLc0wLKo5zd123123V4",
"account_id": "99473c28-21cf-4a9a-b79e-fd643dd7a4bc",
"description": "Macbook Pro 16\" 512GB",
"credit_debit_indicator": "debit",
"amount": {
"value": "2300.00",
"currency": "USD"
},
"date_time": "2023-11-08T02:07:14Z",
"status": "booked",
"enrichments": {
"categories": {
"l1": {
"slug": "shopping",
"confidence": "0.97"
},
"l2": {
"slug": "electronics_appliances_and_technology",
"confidence": "0.97"
}
}
}
},
{
"transaction_id": "dZyaKRwkKZULmmkd0wkLc0wLKo5zd123123V5",
"account_id": "99473c28-21cf-4a9a-b79e-fd643dd7a4bc",
"description": "Starbucks",
"credit_debit_indicator": "debit",
"amount": {
"value": "23.00",
"currency": "USD"
},
"date_time": "2023-11-02T02:07:14Z",
"status": "booked",
"enrichments": {
"merchant": {
"id": "d553b681-570a-40d4-b036-24498128b2d2",
"slug": "starbucks",
"display_name": "Starbucks",
"logo": "https://assets.thisisbud.com/bud-datasci-images/merchant_logos/d553b681-570a-40d4-b036-24498128b2d2/v2/starbucks.jpeg"
},
"categories": {
"l1": {
"slug": "food_and_drink",
"confidence": "0.99"
},
"l2": {
"slug": "coffee",
"confidence": "0.99"
}
}
}
}
]
}
],
"metadata": {
"task_id": "1700fc19-5d58-4610-bb20-3483204e72b2",
"next_url": "/v2/ingest/status/1700fc19-5d58-4610-bb20-3483204e72b2",
"next_url_delay": 500
}
}
Asynchronous Processing Mode - Example Response
In asynchronous mode, if the ingest transactions request has been successful the response will contain the task_id with no partially enriched transactions.
{
"operation_id": "v2_ingest_transactions_post",
"metadata": {
"task_id": "6cac2adb-3b4e-4b15-a6aa-ac24ee513be5",
"next_url": "/v2/ingest/status/6cac2adb-3b4e-4b15-a6aa-ac24ee513be5",
"next_url_delay": 500
}
}
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 customer ID has not been included in the request.
{
"operation_id": "v2_ingest_transactions_post",
"code_id": "failed_validation",
"message": "validation failure(s) in request payload",
"errors": {
"customers[0]": {
"customer_id": "The customer ID is mandatory"
}
}
}
If your request is missing required fields within the transactions block this will also be communicated in the errors object as shown in the example below.
{
"operation_id": "v2_ingest_transactions_post",
"code_id": "failed_validation",
"message": "validation failure(s) in request payload",
"errors": {
"8a4eb421-3d10-48ef-a39e-959cd52c9b54": {
"invalid_fields": {
"transactions[0]": [
"amount",
"date_time"
]
},
"missing_fields": {
"transactions[0]": [
"description"
]
}
}
}
}
In both of these cases it is important to use the errors object to understand why the request is failing and to update any fields before resending the request
How will I know when the First Party Ingestion process is complete?
Once you have received a task_id back from the ingest transactions endpoint, we recommend using one of the following options to check the first party ingestion process has completed. Please integrate the option that works best for your application:
- Call the retrieve ingestion task status endpoint as per the following API document.
- Set up the first party ingestion webhook so that we can notify you as soon as the ingestion process is complete. A full guide on how to set up webhooks can be found here, and more details about the First party ingestion webhook can be found here.
Viewing the Enriched Transactions
Once you receive notification that the first party ingestion process is complete, you can then view the enriched transactions by using the V2/transactions endpoint. This endpoint will then return a list of all the ingested transactions for the customer, along with the Bud enrichments which will be returned within the enrichments block as shown in the example below.
"enrichments": {
"categories": {
"l1": {
"slug": "eating_out",
"confidence": "0.99"
},
"l2": {
"slug": "cafes_and_eating_out",
"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"
},
"processor": {
"id": "18f63293-0217-4520-bbf0-071dca7a9d04",
"slug": "paypal",
"display_name": "PayPal",
"logo": "http://url/paypal_logo.jpeg"
},
"regularity": {
"frequency": "monthly",
"predicted_date_times": [
"2022-06-28T15:00:00Z00:00",
"2022-07-28T15:00:00Z00:00",
"2022-08-28T15:00:00Z00:00"
],
"group_label": "a_group_id"
},
"transaction_types": [
"card",
"debit"
],
"names": [
"jane doe"
]
}
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 14 days ago