Set up 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).
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.
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": "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.
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 6 months ago