Guides
Postman collections ↗Bud Console ↗

Set up First Party Ingestion

How to successfully ingest customer transactions into the Bud Platform.

Suggest Edits

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).

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.

🚧

Only integrate First Party Ingestion endpoints if you already have access to your customers raw accounts and transactions data. The standard way to access your customers accounts and transactions data is using the Bud Connect journey which does not use these endpoints.

Pre-requisites

Before starting you'll need to:

  • Get access to Bud's API services by signing up to the Bud Console (log in | info)
  • 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

👍

Get started quicker with our Postman Collection

To use the Postman collection, download here and import both the collection and the environment files into postman (more info and steps 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 categorisation 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 categorisation 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.

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": "GBP"
            },
            {
                "transaction_id": "dZyaKRwkKZULmmkd0wkLc0wLKo5zd123123V5",
                "description": "Starbucks",
                "account_id": "99473c28-21cf-4a9a-b79e-fd643dd7a4bc",
                "date_time": "2023-11-02T02:07:14Z",
                "amount": "-23.00",
                "currency": "GBP"
            }
        ],
        "transaction_windows":
        [
            {
                "account_id": "99473c28-21cf-4a9a-b79e-fd643dd7a4bc",
                "start": "2023-11-01T23:00:00Z",
                "end": "2023-11-10T23:00:00Z"
            }
        ]
    }
]

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.

RecommendedHard Limit
5001000

📘

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": "GBP"
                    },
                    "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": "GBP"
                    },
                    "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 /financial/v2/transactions endpoint (here). 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 wish to delve deeper into Bud’s capabilities you can do so by exploring our additional enrichment and insights APIs.

Transaction Status Lifecycle

Transactions can be ingested with a status of pending, booked or declined, with booked being the default value when no status is specified.

When transactions settle and either move to booked or declined, the Book Transactions V3 and Decline Transactions V3 endpoints should be called respectively.

Using these endpoints you can supply the transaction_id of the transactions to be settled and the date_time when the settlement occurred for each transaction.

When transactions are then subsequently fetched from Retrieve Transactions V2, their status' will reflect the settlement that has been applied.

Any new transactions should then subsequently be ingested in a new ingestion request.

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 5 months ago