View postman ↗Get API Keys ↗

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

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

Ingest transactions for each Customer

With your headers set and your customer created you can start uploading and enriching your customers 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's important to use the error object to understand why the request is failing and to update any fields before re-sending the request.

Asynchronous

If you have included the header X-Disable-Synchronous: true and are 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.

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"
    ]
}

Limits

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

SynchronousAsynchronous
Transactions10,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 19 hours ago