Guides
Postman collections ↗Bud Console ↗

Setup first party data enrichment

Suggest Edits

Below we’ll provide you with a step-by-step guide to help you integrate with Bud and use our categorisation and data enrichment services on transactional data that you already hold on your customers. Please note, the same enrichment services will also be applied to transaction data aggregated through Bud Connect.

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

Bud's POST v2/ingest/transactions endpoint (here) can work both synchronously and asynchronously dependent on your needs and requirements. You can switch between the two by including the header X-Disable-Synchronous: true. If the header is present and set to true, the process will be entirely 'non-blocking', with the returned Task ID providing access to the status of the full enrichment process. When the endpoint is acting synchronously it initiates a 'blocking' ingestion and enrichment process.

Please note that only transaction-level enrichments will be applied to the data when processing synchronously (i.e. categorisation, and entity extraction and standardisation). In order to obtain account-level enrichments, (e.g. regular or upcoming payments), the results must be obtained in an asynchronous manner.

Synchronous Processing

By default, the endpoint will process the transactions synchronously, meaning certain enrichments will be returned in the response. This is to cater to use cases where clients might need access to the enriched data as quickly as possible, i.e. without having to wait for the more lengthy enrichments to complete. Generally, we recommend using smaller batch sizes when processing synchronously. We recommend a batch size between 200-500 transactions per request.

Please note that further enrichments will also be applied asynchronously, the results of which can be obtained by making a request to the relevant GET data endpoint. With your customer created you can start uploading and enriching your customer's transactions.

You can see an example request below.

  {
    "customer_id": "bcc3ec49-3487-4646-a367-f6147e085c5f",
    "customer_secret": "10cD6ce13b4fda35ba7a5665893cdda67e6f0e7d44562579f0dc07500",
    "transactions": [
	 {
				"transaction_id": "d2ea249c-0d1b-4346-b88e-53ec8bc32083",
				"account_id": "32352b68-76de-408b-a451-22e37803271a",
				"description": "Tesco",
				"amount": "15.69",
				"currency": "GBP",
				"date_time": "2022-11-11T12:00:00Z"
			}
	]
  }

If the request has been successful you can expect to see the enriched transactions and a task-id in the response.

{
    "operation_id": "v2_ingest_transactions_post",
    "data": [
        {
            "customer_id": "bcc3ec49-3487-4646-a367-f6147e085c5f",
            "enriched_transactions": [
               {
					"transaction_id": "d2ea249c-0d1b-4346-b88e-53ec8bc32083",
					"account_id": "32352b68-76de-408b-a451-22e37803271a",
					"description": "Tesco",
					"credit_debit_indicator": "debit",
					"amount": {
						"value": "15.69",
						"currency": "GBP"
					},
					"date_time": "2022-11-11T12:00:00Z",
					"status": "booked",
					"enrichments": {
						"merchant": {
							"id": "17ac2742-8c93-4c11-a01f-17ad65b950ce",
							"slug": "tesco",
							"display_name": "Tesco",
							"logo": "https://assets.thisisbud.com/bud-datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v1/tesco.jpeg"
						},
						"categories": {
							"l1": {
								"slug": "groceries",
								"confidence": "0.98"
							},
							"l2": {
								"slug": "supermarkets",
								"confidence": "0.97"
														}
                        }
                    }
                }
            ]
        }
    ],
    "metadata": {
        "task_id": "7f297930-39c9-46e8-8223-ec162318f013",
        "next_url": "/v1/ingest/transactions/7f297930-39c9-46e8-8223-ec162318f013",
        "next_url_delay": 50
    }
}

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 that the customer ID, customer secret and transactions list have 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",
         "customer_secret":"The customer secret is mandatory",
         "transactions":"The transactions list is mandatory"
      }
   }
}

If your request is missing specific fields in the transactions 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 error object to understand why the request is failing and to update any fields before re-sending the request.

Asynchronous Processing

If you have included the header X-Disable-Synchronous: true and are only using the endpoint asynchronously you can use the GET v1/ingest/transactions/{task_id} endpoint (here) to confirm that the transactional data was successfully ingested. This is to cater for those use cases that favour larger batch sizes over latency.

You can find an example of the request below.

curl --location --request GET 'https://api-sandbox.thisisbud.com/v1/ingest/transactions/7f297930-39c9-46e8-8223-ec162318f013' \
--header 'X-Client-Id: fc2437eb-f867-4de6-8f55-7bd5bba928e8' \
--header "Authorization: Bearer $TOKEN"

This endpoint will then return the status of the task.

{
    "operation_id": "ingest_transactions_get",
    "data": {
        "id": "7f297930-39c9-46e8-8223-ec162318f013",
        "status": "Completed",
        "sub_tasks": [
            {
                "id": "bcc3ec49-3487-4646-a367-f6147e085c5f",
                "customer_id": "bcc3ec49-3487-4646-a367-f6147e085c5f",
                "status": "Completed",
                "error": {}
            }
        ]
    }
}

Viewing the transactions

With the transactional data now uploaded you can view the enriched transactions by using theGET v2/transactions endpoint (here).

You can find an example of a request below.

curl --location --request GET 'https://api-sandbox.thisisbud.com/financial/v2/transactions?date_from=2020-01-01&date_to=2023-10-10&page_size=100' \
--header 'X-Client-Id: fc2437eb-f867-4de6-8f55-7bd5bba928e8' \
--header 'X-Customer-Id: bcc3ec49-3487-4646-a367-f6147e085c5f' \
--header "X-Customer-Secret: 10cD6ce13b4fda35ba7a5665893cdda67e6f0e7d44562579f0dc07500' \
--header "Authorization: Bearer $TOKEN"

This endpoint will then return a list of all transactions attached to the customer-Id specified in the header of the request. Each transaction will contain;

  • A primary and secondary transaction category, each with a confidence value;
  • Merchant and/or processor Id, name and logo;
  • Regular payment details and tag (where the transaction is part of a regular group);
  • Any transaction types associated with the transaction;
  • Any names associated with the transaction.
"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"
	]
}

Batch Sizes

You can find below the recommended and hard limits regarding the number of transactions and customers that can be handled in a single request.

RecommendedSynchronousAsynchronous
Transactions2005,000
Customers1<10
Hard LimitSynchronousAsynchronous
Transactions1,00010,000
Customers100500

If you wish to delve deeper into Bud’s capabilities you can do so by exploring our additional enrichment and insights APIs.

📘

These can be found under their respective folders in the Postman collection.




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 1 year ago