openapi: 3.0.3
info:
title: 'Bud API Services: Documentation'
version: 2.10.10
description: |-
# Overview
## Introduction
Welcome to Bud's API Platform documentation. Here you will find everything you need to build features, apps and experiences using Bud's API Services. All endpoints follow standard RESTful principles and example request and response payload snippets are provided to get you up and running quickly and easily.
To start interacting with our platform, please sign up for access [here](https://www.thisisbud.com/developers#developer-console). You will be provided with access to the [Bud Developer Console](https://console.thisisbud.com) where you can create the API Credentials required to obtain an OAuth2 access token.
If you have any questions, please use our [Support Centre](https://support.thisisbud.com/hc/en-gb) or email us on [help@thisisbud.com](mailto:help@thisisbud.com).
## Bud Platform Products
| Product | Service | Description |
|--|--|--|
| Connect | Open Banking Aggregation API | Simplified and unified access to Open Banking Aggregation APIs. |
| Connect | First Party Ingestion API | Push your own data onto the Bud platform via Bud's first party ingestion endpoints. |
| Intelligence | Financial Data API | Obtain enriched first and third party transactional data. |
| Intelligence | Enrichment API | Access enrichment resources and retrieve high level aggregations of transactional data. |
| Intelligence | Financial Insights API | Obtain a deeper understanding of your customers transactional data through a variety of different insights. |
| Intelligence | Signal API | Contextual, relevant triggers and notifications that drive action from customers. |
| Intelligence | Financial Review API | Pre-fill affordability forms to speed up services and reduce drop-off with custom groups of income and spending. |
| Pay | Payments API | Make authorised payments and transfers directly from a customer’s account. |
| Check | KYC API | Perform relevant checks against businesses and customers. |
## Environments and API Base URIs
Bud currently supports two environments on its platform:
1. Bud’s Sandbox Environment - [https://api-sandbox.thisisbud.com/](https://api-sandbox.thisisbud.com/)
2. Bud’s Production Environment - [https://api.thisisbud.com/](https://api.thisisbud.com/)
## Bud’s Sandbox Environment
### About
Bud Sandbox Platform is a development environment for integrating and testing Bud’s services. Its version is kept up to date with production. Bud’s sandbox environment mirrors our production environment and all updates are made in tandem. On the Sandbox environment, the variety of providers that you can connect to via Open Banking is limited and contains a predefined set of dummy accounts and transaction data. The instance size doesn’t differ from production, although certain rate limits are in place.
### API Access
To start interacting with Bud’s Sandbox API you have to sign up for a developer account [here](https://www.thisisbud.com/developers#developer-console).
Once you’ve completed the signup and activation process you will be able to create a new project in the [Developer Console](https://console.thisisbud.com) to receive API Credentials (client_id and client_secret). These can be used to obtain OAuth2 access and refresh tokens using authentication endpoint. The access token must be supplied as a Bearer token within every service API call made to the Bud Platform. Once the access token has expired, the refresh token must be used to obtain another access token.
Details on the authentication process can be found in the Authentication section of this documentation.
### Sandbox Providers
Bud’s sandbox is built to mirror its production environment. The main difference is the available open banking providers that a customer is able to connect to. In the sandbox, Bud’s aggregation service only supports the use of Open Banking sandbox providers which issue dummy data.
Currently, you are able to connect to customer profiles with predefined accounts and transaction data sets (managed by Bud) which are available via the NatWest Sandbox provider.
From a Marketplace perspective, you can test any available journeys and play around with them, see how the product is constructed, what information the endpoints return and potentially create a new product of your choosing, following the API journey. Please note, that you will be unable to physically carry out any of the marketplace journeys (e.g. send rental data to Experian, or switch your Utility provider) within the Sandbox environment.
Necessary access credentials can be found in the Bud [Developer Console](https://console.thisisbud.com) interface.
## Bud’s Production Environment
### About
Bud’s production environment is designed for use within your application when going live to real Customers. The environment is fully scalable, secure and facilitates the use of real Customer data.
### API Access
To start interacting with Bud’s Production environment you must first sign up for a developer account [here](https://www.thisisbud.com/developers#developer-console). Once you have been assigned a relevant account manager, please contact them to get access to Bud’s production environment.
### Providers
Bud’s production environment provides live access to all currently available providers via the Bud Platform (i.e. third party products and services). Please click here for a list of the currently supported Open Banking providers available via Buds Open Banking Aggregation API. This list is updated as and when new providers are on boarded onto the Bud platform.
The production environment allows your Customers to connect to additional third party products and services via the Bud platform. A list of the different Investment and Pension Aggregation providers can be seen here. Information surrounding additional third party providers, relevant to a specific marketplace journey, can be found in the relevant documentation below.
## Message formats
Bud’s platform is made available through Application Programming Interface (API) endpoints, all of which adhere to [RESTful](https://restfulapi.net/) principles. Standard HTTP verbs and status codes are used for requests and response statuses. Request and response payloads are [JSON](http://www.json.org/) encoded data formatted. Communication with the Bud Platform is handled over HTTPS protocol only.
| Data Type | Standard |
| -- | -- |
| Strings encoding | `UTF-8` |
| Datetime | `ISO 8601` |
| Currency codes | `ISO 4217` |
### HTTP Verbs
| Verb | Usage Context |
| -- | -- |
| GET | Used to retrieve the resource representation or metadata |
| POST | Used to create a new resource on the server |
| PUT | Used to update the resource state |
| PATCH | Used to partially update a resource |
| DELETE | Used to delete the resource|
### HTTP Response Codes
| Code Class | Description |
| -- | -- |
| `1XX` | Informational - provisional response from the server |
| `2XX` | Success - the request has been processed successfully by the server |
| `4XX` | Client Error - the request has not been processed due to client-side issue with the request |
| `5XX` | Server Error - the request has not been processed due to server-side issue |
## Requests Custom Headers
Some endpoints will require the presence of custom headers in the HTTP Request to be properly processed by Bud Platform services.
| Header Name | Description|
| ----------- | ---------------------------- |
| `X-Client-Id` | API Credentials `client_id` value required for request authorisation purposes |
| `X-Customer-Id` | Customer Identifier value necessary for establishing the Customer context of the data to be retrieved or processed |
| `X-Account-Id` | Customer Account Identifier value necessary for establishing the context to retrieve specific customer’s account data.|
| `X-From` | Start date from when the transactions data should be returned |
| `X-To` | End date till when the transactions data should be returned |
## Response Styling
### Response Custom Headers
| Header Name | Description |
| -- | -- |
| `X-Request-Id` | Bud request identifier for troubleshooting purposes |
## Success Responses
The description and the listed status codes below indicate that an action requested by the client was successfully processed.
The successful responses will have status codes in the `200-299` range and have relevant response content where required. However, `204 No Content` and `205 Reset Content` status codes won't contain a response content.
### Response Style Properties
| Field | Description | Properties |
| ------------ | -------------------------------------------------------------------- | --------------------------------------------- |
| operation_id | A descriptive enough string that is linked to the operation/feature. | A `required` lower case snake case `string` |
| data | A data-set that is relevant to the endpoint. | An `optional` single/multidimensional `array` |
| metadata | Contains endpoint specific additional information. | An `optional` JSON `object` |
#### Examples
##### 200 OK
After getting an existing resource with `GET /resources/{id}`.
```json
{
"operation_id": "resources_get",
"data": {
"id": "111-AAA-222-BBB",
"name": "Bud",
"email": "bud@thisisbud.com",
"created_at": "2019-01-01T15:53:00+05:00"
}
}
```
##### 201 Created
After creating a new resource with `POST /resources`.
```json
{
"operation_id": "resources_post",
"data": {
"id": "111-AAA-222-BBB"
}
}
```
## Error Responses
### Response Style Properties
| Field | Description | Properties |
| ------------ | ----------------------------------------------------------------------- | --------------------------------------------- |
| operation_id | A descriptive enough string that is linked to the operation/feature. | A `required` snake case `string` |
| code_id | A descriptive enough string that is linked to the reason for the error. | A `required` snake case `string` |
| message | An actual user friendly error message. | A `required` `string` |
| metadata | Contains endpoint specific additional information. | An `optional` JSON `object` |
| errors | A data-set that is relevant to the error. | An `optional` JSON `object` |
### Client Error Responses
The description and the listed status codes below indicate that the action requested by the client was not successfully processed due to apparent client errors in the request.
The client errors will have status codes in the 400-499 range and have relevant response content where required.
#### Generic Client Error Responses
| Error Code | Cause | Response Body |
|--------------|---------|-----------|
|401|Unauthorized|`{"operation_id": "unknown","code_id":"unknown","message": "Unauthorised request","errors": {}}` |
|404|Not Found|`{"operation_id": "unknown","code_id":"unknown","message": "Route or resource not found","errors": {}}` |
|405|Method Not Allowed|`{"operation_id": "unknown","code_id":"unknown","message": "Method not allowed","errors": {}}` |
#### List of Code Ids
| Name | Description |
|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| failed_validation | Occurs when a request validation process fails. |
| invalid_login | Occurs when insufficient login credentials were provided. |
| resource_not_found | Occurs when a requested record or a feature was not found. |
| unique_constraint | Occurs when a request tries to create an existing record in database. |
| task_not_found | The specified task could not be found. |
| account_not_found | The specified account could not be found. Please check the account identifier is correct. The account might be closed or suspended. |
| internal_error | An unexpected internal error. |
| internal_timeout | A task had timed out. |
| internal_transient_error | A unexpected transient internal error. |
| request_validation | Occurs when a request validation process fails. |
| auth_denied | Authorisation process cancelled. |
| auth_expired | The authorisation url has expired. Please generate a new one to continue. |
| connection_not_found | No active connection with the provider |
| connection_expired | The connection consent has expired. re-authentication required |
| connection_revoked | The connection consent has been revoked. Re-authentication required |
| connection_status | The connection consent is in the wrong status to perform the action. |
| connection_permission | The connection consent does not have the require permissions for this resource |
| provider_not_found | Unknown provider |
| provider_failure | The provider has had an unexpected failure |
| provider_timeout | The provider has taken to long to respond. |
| provider_maintenance | The provider is temporarily unavailable due to maintenance |
| provider_request_limit | The provider rate limit has been exceeded |
| provider_endpoint_unimplemented | The provider has not implemented this endpoint |
| provider_endpoint_deprecated | The provider has deprecated this endpoint |
| provider_reauthenticate | The provider has deemed this consent needs to be reauthenticated. |
#### Examples
##### 400 Bad Request
Returned after a failed attempt to create a new resource by passing invalid data to POST /resources.
After trying to create a new resources by passing invalid data to `POST /resources`.
```json
{
"operation_id": "resources_post",
"code_id": "failed_validation",
"message": "Invalid request payload.",
"metadata": {},
"errors": {
"name": "This value is required.",
"email": "This value is invalid."
}
}
```
### Server Error Responses
The server errors will have status codes in the 500-599 range. The server errors will look very much like the "Client Errors" but will contain bare minimum information attached to them.
#### Generic Server Error Responses
| Error Code | Cause | Response Body |
|--------------|---------|-----------|
|`500`| Internal Server Error| `{"message": "An error occurred while processing your request"}`|
|`503`| Service Unavailable| `{"message": "Service unavailable"}` |
# Updates & Versioning
Updates to Bud's API documentation are made frequently. The current version of the documentation can be clearly viewed at the very top of this page.
## Backward Compatibility
Bud aims to make integration as seamless as possible for its clients and therefore takes all possible steps to prevent backward-compatibility breaks. In the scenario where a backward-compatibility break is unavoidable, Bud creates a new endpoint, either: (a) by bumping the version within the endpoint URL; or (b) in some circumstances renaming the URL entirely. The previous endpoint may then become deprecated, and support for the endpoint will cease after a period of three months. Clients with access to any of Bud’s API services will be notified of deprecations to any endpoints and provided with ample time in which to make any necessary changes.
Fields within response or request schemas may also become deprecated. Along with deprecated endpoints, these breaking changes will be clearly highlighted within the below changelog.
## Deprecations
Bud will continue to support deprecations for a period of **three months** after they are first announced.
| Date of Announcement | Deprecation Details |
|:---------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 04/12/2020 | Changed the base URL of the **GET Warnings**, **GET Trends** and **GET Forecast** endpoints from `/v1/assistant/` to `/v1/signal/`. |
| 06/08/2020 | Removed `bank_name` field in favour of a new field called `provider` in the following endpoints:
__POST__`/v1/open-banking/authorisation-url` (Request Payload)
__POST__`/v1/open-banking/connect/{connection_task_id}` (Response Payload)
__POST__`/v1/open-banking/refresh/{task_id}` (Response Payload) |
| 01/09/2021 | Deprecated **GET Warnings** endpoints in favour of new **GET Money Management**, **GET Customer Characteristics** and **GET Financial Insight** endpoints. |
| 01/11/2021 | Deprecated **Retrieve Authorisation Gateway URL** endpoint in favour of new **Retrieve Authorisation Gateway URL (v2)** endpoint. |
| 01/11/2021 | Deprecated **Energy Switching API**, **Mortgage API**, **Home Insurance API** and **Broadband API** which formed Bud's marketplace offering. |
| 14/03/2022 | Deprecated **Enrich Transaction** endpoints from the Ingest and Enrich API suite. |
| 01/08/2022 | Deprecated `YYYY-MM-DD` date format for `X-From` and `X-To` headers within `/v1/affordability/spending-groups`. Both `X-From` and `X-To` headers now follow the `YYYY-MM` date format. |
| 05/09/2022 | Deprecated **Retrieve Merchant Totals V1** in favour of new **Retrieve Merchant Totals V2** endpoint |
| 23/01/2023 | Deprecated **List Transactions V1**. Bud understands that many clients have integrated this endpoint in order to retrieve transactions held on the Bud platform. As a result, there is a **six month** deprecation window, meaning that support for this endpoint will cease on the **1st of August 2023**, meaning clients must have migrated over to the new and improved **List Transactions V2** endpoint by that point in time. |
| 23/01/2023 | Deprecated **Create Customers V1**. Support will continue for this endpoint, however we recommend clients to migrate to V2 and for all new clients to integrate with the V2 endpoint. |
| 24/03/2023 | Deprecated **Retrieve Accounts** endpoint. Bud understands that many clients have integrated this endpoint in order to retrieve accounts held on the Bud platform. As a result, there is a **six month** deprecation window, meaning that support for this endpoint will cease on the **24th of September 2023**, meaning clients must have migrated over to the new and improved **Retrieve Accounts V2** endpoint by that point in time. |
| 28/03/2023 | Deprecated **Retrieve Financial Forecast** in favour of **Retrieve Forecasted Transactions V2**. |
| 28/03/2023 | Deprecated **Create Transaction Rule(s)**. |
| 28/03/2023 | Deprecated **Retrieve Trends** in favour of **Retrieve Category Totals**. |
| 22/06/2023 | Deprecated **Retrieve Forecasted Transactions V1** in favour of **Retrieve Forecasted Transactions V2**. |
| 25/07/2023 | Deprecated **Retrieve Income Transactions V1** in favour of **Retrieve Income Transactions V2**. |
| 25/07/2023 | Deprecated **Retrieve Salary Information V1** in favour of **Retrieve Income Transactions V2**. |
| 17/08/2023 | Deprecated **Submit Authorisation Codes** in favour of **Submit Authorisation Codes V2**. |
| 04/10/2023 | Deprecated **Open Banking Sync Complete** callback in favour the **Connect Completed Notification Callback** and **Refresh Completed Notification Callback** callbacks. |
| 18/10/2023 | Deprecated **Retrieve Transaction Ingestion Task Status** in favour of **Retrieve Ingestion Task Status**. |
| 18/10/2023 | Deprecated **Retrieve Accounts Ingestion Task Status** in favour of **Retrieve Ingestion Task Status**. |
| 15/01/2024 | Deprecated **Remove Customer** in favour of **Remove Customer V3**. |
| 15/01/2024 | Deprecated **Compare Custom Insight**, **Retrieve Custom Insight**, **Create Custom Insight** |
| 25/01/2024 | Deprecated **Retrieve Ingestion Task Status V2** in favour of **Retrieve Ingestion Task Status V3** |
| 21/05/2024 | Deprecated **Initiate Refresh** in favour of **Initiate Refresh V2** (Six month deprecation Notice) |
| 21/05/2024 | Deprecated **Retrieve Refresh Status** in favour of **Retrieve Refresh Status V2** (Six month deprecation Notice) |
| 27/08/2024 | Deprecated **Retrieve Affordability Transactions** in favour of **Retrieve Affordability Transactions V2** (Three month deprecation Notice) |
| 28/08/2024 | Deprecated **Retrieve Balances Over Time** in favour of **Retrieve Balances Over Time V3** (Three month deprecation Notice) |
| 04/09/2024 | Deprecated **Retrieve Account V2** in favour of **Retrieve Account V3** (Six month deprecation notice) |
| 04/09/2024 | Deprecated **Retrieve Account By ID V2** in favour of **Retrieve Account By ID V3** (Six month deprecation notice) |
| 02/10/2024 | Deprecated **Retrieve Affordability Transactions** in favour of **Retrieve Affordability Transactions V2** (Three month deprecation Notice) |
| 27/01/2026 | Deprecated `posted_date_time` field on __Retrieve Transations V2__ in favour of `value_date_time` on __Retrieve Transactions V2__ |
| 27/01/2026 | Deprecated `date-field` parameter on __Retrieve Balances Over Time V3__ |
| 27/01/2026 | Deprecated `date-field` parameter on __Retrieve Balances Over Time By Account V3__ |
## Changelog
This changelog represents a list of all changes that have been made to Bud’s API documentation. This includes both backward-compatible and backward-incompatible changes.
**Version 4.4.0: 30/04/2026**
>- Add `pan` as a valid account identifier type in __Ingest Accounts__.
**Version 4.3.0: 23/04/2026**
>- Add __Generate Savings Goals URL__ endpoint.
**Version 4.2.0: 21/04/2026**
>- Remove deprecated __Savings Goals V1__ endpoints.
**Version 4.1.0: 20/04/2026**
>- Add __Create Savings Goal V2__ endpoint.
>- Add __Retrieve Savings Goals V2__ endpoint.
>- Add __Retrieve Savings Goal V2__ endpoint.
>- Add __Update Savings Goal V2__ endpoint.
>- Add __Remove Savings Goal V2__ endpoint.
**Version 4.0.1: 02/03/2026**
>- Extend description of __Ingest Transactions__.
**Version 4.0.0: 09/02/2026**
>- Add __Remove Customer By Idempotent Identifier V3__ endpoint.
**Version 3.0.0: 09/02/2026**
>- Remove __Create Spending Budget__ `account_id` request body parameter
>- Add `account_id` filtering parameter to __Retrieve Spending Budgets__ endpoint.
>- Add `account_id` filtering parameter to __Retrieve Spending Budget Transactions__ endpoint.
**Version 2.26.2: 27/01/2026**
>- Add `value_date_time` field on __Retrieve Transactions V2__ endpoint.
>- Add `value_date_time` field on __Ingest Transactions__ endpoint request and response.
>- Mark `date-field` parameter as deprecated on __Retrieve Balances Over Time V3__ endpoint.
>- Mark `date-field` parameter as deprecated on __Retrieve Balances Over Time By Account V3__ endpoint.
**Version 2.26.0: 19/01/2026**
>- Add __Generate Spending Budgets URL__ endpoint.
**Version 2.25.2: 12/01/2026**
>- Mark `posted_date_time` field as deprecated on __Retrieve Transactions V2__ endpoint.
**Version 2.25.1: 08/01/2026**
> - Added `exclude_category` parameter to __Category Totals V2__ endpoint.
**Version 2.25.0: 07/01/2026**
>- Add hcst as valid tag being returned from __Retrieve Transactions V2__ endpoint.
**Version 2.24.1: 06/01/2026**
>- Remove `posted_date_time` from __Ingest Transactions__ endpoint request and response.
**Version 2.24.0: 02/12/2025**
>- Add __Retrieve Account Transaction Dates__ endpoint.
**Version 2.23.2: 25/11/2025**
>- Add __Generate Accounts URL__ endpoint.
>- Added `credit_transactions_count` and `debit_transactions_count` fields to __Merchant Totals V2__ response.
**Version 2.23.1: 07/11/2025**
>- Add `provider_display_name` and `provider_logo` fields to __Retrieve Accounts v3__ and __Retrieve Accounts V3 By ID__ response.
**Version 2.23.0: 06/11/2025**
>- Update endpoint url for __Generate Card Summary URL__ endpoint
>- Update endpoint url for __Generate Financial Calendar URL__ endpoint
>- Update endpoint url for __Generate Balances Over Time URL__ endpoint
>- Update endpoint url for __Generate Recurring and Forecasted Transactions URL__ endpoint
>- Update endpoint url for __Generate Spending Analysis URL__ endpoint
>- Update endpoint url for __Generate Intelligent Search Widget URL__ endpoint
**Version 2.22.0: 04/11/2025**
>- Add __Remove Account Data V2__ endpoint.
**Version 2.21.6: 04/11/2025**
>- Update account_type filter values on __Retrive Accounts V3__ request.
**Version 2.21.5: 24/10/2025**
>- Add `counterparty` field to __Ingest Transactions__ request and sync response.
>- Add `suggested_description` field to __Ingest Transactions__ request.
>- Add `opening_date_time` field to __Ingest Accounts__ request.
>- Expanded values for `account_type` field on __Ingest Accounts__ request
>- Add `counterparty` field to __Retrieve Transactions V2__ response.
>- Add `opening_date_time` field to __Retrieve Accounts V3__ response.
>- Add `opening_date_time` field to __Retrieve Accounts V3 By ID__ response.
>- Add `account_category` field to __Retrieve Accounts V3__ response.
>- Add `account_category` field to __Retrieve Accounts V3 By ID__ response.
>- Expand values for `account_type` field on __Retrieve Accounts V3__ response.
>- Expand values for `account_type` field on __Retrieve Accounts V3 By ID__ response.
**Version 2.21.4: 21/10/2025**
>- Add new fields to `metadata` to __Generate Card Summary URL__ request and sync response.
**Version 2.21.2: 30/09/2025**
>- Add `running_balance` field to __Ingest Transactions__ request and sync response.
>- Add `running_balance` field to __Retrieve Transactions V2__ response.
>- Add `holders` field to __Ingest Accounts__ request.
**Version 2.21.1: 29/09/2025**
>- Add `consent_details` to the refresh.v2.* webhooks.
**Version 2.21.0: 25/09/2025**
>- Add __Generate MCP URL__ endpoint.
**Version 2.20.0: 24/09/2025**
>- Add __Close Accounts__ endpoint.
>- Add __Reopen Accounts__ endpoint.
>- Add `status` and `closed_at` fields to __Retrieve Accounts V3__.
**Version 2.19.4: 03/09/2025**
>- Add `posted_date_time` field to __Ingest Transactions__ request and sync response.
**Version 2.19.3: 03/09/2025**
>- Add `updated_after` field to __Retrieve Transactions V2__ metadata.
>- Add `deleted` field to __Retrieve Transactions V2__ metadata.
**Version 2.19.2: 27/08/2025**
>- Add `us_account_number` identifier to __Retrieve Accounts V3__
**Version 2.19.1: 18/08/2025**
>- Update the permissions value returned when listing consents
**Version 2.19.0: 12/08/2025**
>- Add support for use of `customer_idempotent_identifier` field in place of `customer_id` field in __Ingest Accounts__, __Ingest Transactions__, __Book Transactions__, and __Decline Transactions__. This allows for easier integration, and allows customers to automatically be created at the point of ingestion.
**Version 2.18.0: 25/06/2025**
>- Add `X-Customer-Idempotent-Identifier` header to all endpoints that support `X-Customer-Id` header.
**Version 2.17.10: 12/06/2025**
>- Add `idempotent_identifier` filter to __Retrieve Customers V3__.
**Version 2.17.9: 12/06/2025**
>- Updated list of possible tags in __Retrieve Transactions V2__ endpoint response.
**Version 2.17.8: 16/05/2025**
>- Extend `status` query parameter possible values in __Retrieve Financial Data__ endpoint.
>- Extend `status` possible values in __Retrieve Financial Data__ endpoint response.
>- Extend `frequency` possible values in __Retrieve Financial Data__ endpoint response.
**Version 2.17.7: 22/04/2025**
> - Added `account_id` filter to __Category Totals V2__ endpoint.
> - Added `account_id` filter to __Category Totals V2__ trends endpoint.
**Version: 2.15.24: 03/04/2025**
>- Add `subtask_details` object to __FPIIngestSucceededCallback__ and __FPIIngestFailedCallback__.
**Version: 2.15.23: 20/02/2025**
>- Add __Generate Spending Analysis URL__ endpoint.
**Version: 2.15.22: 20/02/2025**
>- Updated list of possible tags in __Retrieve Transactions V2__ endpoint response.
**Version: 2.15.21: 30/01/2025**
>- Add `country_code` field to __Ingest Transactions V2__ request.
**Version: 2.15.20: 23/12/2024**
>- Add new labels parameters to the __Retrieve Categories V2__ endpoint.
**Version: 2.15.19: 10/12/2024**
>- Add __Merchant Feedback__ endpoint.
**Version: 2.15.18: 05/12/2024**
>- Add __Essential Spend Statistics__ endpoint.
**Version: 2.15.17: 02/12/2024**
>- Add __Recurring and Forecasted Transactions URL__ endpoint.
**Version: 2.15.16: 02/12/2024**
>- Add __Generate Balances Over Time URL__ endpoint.
**Version: 2.15.15: 02/12/2024**
>- Add `credit_total` and `debit_total` field metadata of __Category Totals V2__ endpoint response.
**Version: 2.15.14: 02/12/2024**
>- Add __Generate Financial Calendar URL__ endpoint.
**Version: 2.13.7: 26/11/2024**
>- Add `provider` and `transaction_type` field to __Ingest Transactions V2__ endpoint request.
>- Add `transaction_type` field to __Ingest Transactions V2__ endpoint sync response.
>- Add `transaction_type` field to __Retrieve Transactions V2__ endpoint response.
**Version: 2.13.6: 15/11/2024**
>- Add __Generate Card Summary URL__ endpoint.
**Version: 2.13.5: 12/11/2024**
>- Improve `suggested_description` and `suggested_logo` examples for __Retrieve Transactions V2__ endpoint response.
>- Improve `suggested_description` and `suggested_logo` examples for __Ingest Transactions V2__ endpoint response.
**Version: 2.13.4: 11/11/2024**
>- Add `suggested_description` and `suggested_logo` field to __Retrieve Transactions V2__ endpoint response.
>- Add `suggested_description` and `suggested_logo` field to __Ingest Transactions V2__ endpoint sync response.
>- Extend `status` enum with `declined` for __Ingest Transactions V2__ endpoint sync response.
>- Extend `status` description for when `declined` is returned for __Retrieve Transactions V2__ endpoint response.
**Version: 2.13.3: 29/10/2024**
>- Add `X-Bud-Categorisation-Model` header to __Ingest Transactions V2__ endpoint.
**Version: 2.13.2: 23/10/2024**
> - Fixed operation ID for __Retrieve Accounts By ID V3__ endpoint
**Version: 2.13.1: 21/10/2024**
> - Added settlement (book and decline) route enums for __Retrieve Ingestion Task Status V2__ and __Retrieve Ingestion Task Status V3__ endpoint responses.
**Version 2.13.0: 16/09/2024**
> - Added __Book Transactions V3__ endpoint.
> - Added __Decline Transactions V3__ endpoint.
> - Added status filter to __Retrieve Transactions V2__.
**Version 2.12.4: 04/09/2024**
> - Added __Result__ field to __Retrieve Ingestion Task Status V3__ endpoint response.
**Version 2.12.3: 04/09/2024**
> - Deprecated __Retrieve Accounts V2__ endpoint.
> - Deprecated __Retrieve Accounts By ID V2__ endpoint.
**Version 2.12.2: 28/08/2024**
> - Added __Retrieve Accounts V3__ endpoint.
> - Added __Retrieve Accounts By ID V3__ endpoint.
**Version 2.12.1: 01/08/2024**
> - Add status field to __Ingest Transactions V2__ on application/bud-transaction-v3+json format.
**Version 2.12.0: 30/07/2024**
> - Added __Income Expenditure Report Insight Beta__ endpoint.
> - Added __Income Expenditure Report Insight Transactions Beta__ endpoint.
> - Added __Income Health Insight Report Beta__ endpoint.
> - Added __Income Health Report Insight Transactions Beta__ endpoint.
> - Added __Unauthorised Overdraft Insight Report Beta__ endpoint.
> - Added __Unauthorised Overdraft Insight Report Transactions Beta__ endpoint.
> - Added __Merchant Report Insight Beta__ endpoint.
> - Added __Merchant Report Insight Transactions Beta__ endpoint.
**Version 2.11.5: 29/07/2024**
> - Added new __Correction Merchant Search__ endpoint under __Correct Financial Data__.
> - Added new __Correct Transaction Merchant__ endpoint under __Correct Financial Data__.
**Version 2.11.4: 24/07/2024**
> - Remove body requirement from __Reconfirm Consent__
**Version 2.11.3: 01/07/2024**
> - Added link to __Consents__ guide from __Retrieve Customer Consents__
**Version 2.11.2: 21/06/2024**
> - Added __website__ field to merchant field in enrichments field in __Retrieve Transactions V2__.
> - Added __website__ field to processor field in enrichments field in __Retrieve Transactions V2__.
**Version 2.11.1: 19/06/2024**
> - Added a new __Correct Financial Data__ section within __FINANCIAL DATA API__.
> - Relocated __Correct Transaction Categories V2__ endpoint to __Correct Financial Data__ from __Manage Financial Data__.
> - Added new __Similar Transactions__ endpoint under __Correct Financial Data__.
> - Added new __Similar Transactions Including Merchants__ endpoint under __Correct Financial Data__.
**Version 2.11.0: 17/05/2024**
> - Added __Initiate Refresh V2__ endpoint.
> - Added __Retrieve Refresh Status V2__ endpoint.
> - Deprecated __Initiate Refresh__ endpoint in favour of __Initiate Refresh V2__ endpoint (Six month deprecation period).
> - Deprecated __Retrieve Refresh Status__ endpoint in favour of __Retrieve Refresh Status V2__ endpoint (Six month deprecation period).
**Version 2.10.10: 17/05/2024**
>- Add optional `X-Customer-Ip-Address` header to __Initiate Refresh__.
**Version 2.10.9: 05/03/2024**
> - Added insight type as a string on Balances, Income and Spending insights endpoints.
> - Added link to Actionable Insights guide as a note on Balances, Income and Spending insights endpoints.
**Version 2.10.8: 08/02/2024**
> - Fixed path for __Custom Insights__ endpoints.
**Version 2.10.7: 02/02/2024**
> - Added new fields for __Retrieve Balances Over Time__ and __Retrieve Balances Over Time By Account__ endpoint.
**Version 2.10.5: 25/10/2024**:
> - Add provider field to the __OBWebhookBody__ and __OBSyncWebhookBody__ schemas.
**Version 2.10.3: 25/01/2024**:
> - Deprecated __Retrieve Ingestion Task Status V2__ endpoint in favour of __Retrieve Ingestion Task Status V3__ endpoint.
**Version 2.10.2: 24/01/2024**
> - Document has_new_transactions and reconnect_required Refresh Callback Webhook values.
**Version 2.10.1: 24/01/2024**
> - Removed the deprecated __Retrieve Financial Forecast__ endpoint.
> - Removed the deprecated __Retrieve Trends__ endpoint.
> - Removed the deprecated __Retrieve Financial Insights__ endpoint.
> - Removed the deprecated __Retrieve Energy Payments__ endpoint.
> - Removed the deprecated __Energy Payments Discover__ endpoint.
> - Removed the deprecated __Retrieve Category Totals__ endpoint.
> - Removed the deprecated __Create Transaction Rule__ endpoint.
> - Removed the deprecated __Correct Transaction Categories__ endpoint.
> - Removed the deprecated __Retrieve Money Management__ endpoint.
**Version 2.9.13: 18/01/2024**
> - Updated description for __Retrieve Balances Over Time__ and __Retrieve Balances Over Time By Account__ endpoint.
**Version 2.9.12: 15/01/2024**
> - Deprecate __Remove Customer__ endpoint in favour of the __Remove Customer V3__ endpoint.
> - Added __Remove Customer V3__ and __Retrieve Remove Customer__ V3 Status endpoints.
**Version 2.9.11: 12/12/2023**
> - Updated __Reconfirm Consent__ description to include a note about which clients can use the endpoint.
**Version 2.9.10: 07/12/2023**
> - Updated __Create Customer V3__ endpoint to include `created_at` and a new 200 response for existing customers.
**Version 2.9.9: 06/12/2023**
> - Fixed __Retrieve Future Transactions V2__ change\_percentage query parameter example.
**Version 2.9.8: 05/12/2023**
> - Updated the description on __Retrieve Accounts V2__ endpoint to include new account types.
**Version 2.9.5: 29/11/2023**
> - Added the `categories` field to the __Retrieve Future Transactions V2__ endpoint.
> - Update the examples for the __Retrieve Subscriptions V1__ endpoint.
**Version 2.9.4: 09/11/2023**
> - Removed the deprecated __Retrieve Future Transactions V1__ endpoint.
> - Removed the deprecated __Retrieve Income Transactions V1__ endpoint.
> - Removed the deprecated __Retrieve Salary Information__ endpoint.
> - Moved the __Retrieve Benefits Totals__ endpoint from the __Enrichment Totals__ API to the __Smart Finders__ API.
**Version 2.9.3: 26/10/2023**
> - Added Spending Budget endpoints (Create, Update, Delete, Retrieve and Retrieve Transactions) to the __Goals API__.
**Version 2.9.2: 04/10/2023**
> - Deprecated __Open Banking Sync Complete__ callback in favour of the task type specific callbacks __Connect Completed Notification Callback__ and __Refresh Completed Notification Callback__.
> - Add __Consent Revoked Notification Callback__ and __Consent Reconfirmed Notification Callback__ callbacks.
**Version 2.9.1: 28/09/2023**
> - Fixed __Submit Authorisation Codes V2__ description where the reference to __Retrieve Connection Status__ was incorrectly set.
**Version 2.9.0: 21/09/2023**
> - Add __Goals API__.
**Version 2.8.25: 20/10/2023**
> - Added the `idempotent_identifier` attribute to the __Create Customer V3__ endpoint.
> - Removed documentation for __List Transactions V1__ and __Retrieve Accounts V1__ endpoints as passed the deprecation due date.
**Version 2.8.24: 18/10/2023**
> - Deprecated __Retrieve Transaction Ingestion Task Status__ endpoint in favour of __Retrieve Ingestion Task Status__ endpoint.
> - Deprecated __Retrieve Accounts Ingestion Task Status__ endpoint in favour of __Retrieve Ingestion Task Status__ endpoint.
**Version 2.8.19: 06/10/2023**
> - Corrected __Goals API__ to utilise RFC-3339 timestamps
**Version 2.8.15: 20/09/2023**
> - Added __Authorised Payments V2__
**Version 2.8.14: 05/09/2023**
> - Remove the __Retrieve Authorisation Gateway URL__ endpoint.
**Version 2.8.13: 29/08/2023**
> - Deprecated the __Correct Transaction Categories V1__ endpoint (with a deprecation date of 1st December 2023) in favour of __Correct Transaction Categories V2__.
> - Added a deprecation date of 1st December 2023 to the following endpoints: __Create Transaction Rule(s)__, __Retrieve Category Totals__, __Initiate Energy Payments Discovery__, __Retrieve Energy Payments__, __Retrieve Money Management__, __Retrieve Customer Characteristics__, __Retrieve Financial Insights__, __Retrieve Trends__, __Retrieve Financial Forecast__.
**Version 2.8.12: 17/08/2023**
> - Deprecated the __v1_affordability_spending_groups_post__ endpoint in favour of __aggregations_v2_buckets_post__
**Version 2.8.11: 17/08/2023**
> - Added the `Submit Authorisation Codes V2` endpoint
> - Deprecated the `Submit Authorisation Codes` endpoint
**Version 2.8.10: 16/08/2023**
> - Added bucket endpoints
**Version 2.8.9: 08/08/2023**
> - Added `download_data`, `reconfirm_consent` and `revoke_consent` to the `initial_screen` options for the __Retrieve Authorisation Gateway URL V2__ endpoint
> - Deprecated the `reconfirm_consent` body parameter for the __Retrieve Authorisation Gateway URL V2__ endpoint
**Version 2.8.8: 02/08/2023**
> - Fixed error in __Category Totals V2__ path
> - Fixed error in __Category Totals V2__ include L2 attribute
**Version 2.8.7: 28/07/2023**
> - Removed the __Retrieve Financial Products__ endpoint as the deprecation notice has expired.
**Version 2.8.6: 25/07/2023**
> - Removed the __Retrieve Categories V1__ endpoint as the deprecation notice has expired.
> - Deprecated the __Retrieve Income Transactions V1__ endpoint in favour of __Retrieve Income Transactions V2__
> - Deprecated the __Retrieve Salary Information__ endpoint in favour of __Retrieve Income Transactions V2__
**Version 2.8.5: 19/07/2023**
> - Added the __Category Totals V2__ endpoint.
> - Added the __Category Totals V2__ trends endpoint.
> - Fixed bug in v1 category totals schema.
**Version 2.8.4: 19/07/2023**
> - Added `mobile_only` flag for providers in the __Retrieve OB Providers__ endpoint.
**Version 2.8.3: 18/07/2023**
> - Added link to guide to __Create Customers V3__ and __Create Customers V3 (Batch)__.
> - Added link to guide to __Retrieve Accounts V2__ and __Retrieve Accounts By ID V2__.
**Version 2.8.2: 10/07/2023**
> - Added `skip_success_screen` to the request body of the __Retrieve Authorisation Gateway URL V2__ endpoint.
**Version 2.8.1: 07/07/2023**
> - Added `loan` and `pending` tags as part of the __Retrieve Transactions V2__ endpoint.
> - General bug fixes and improvements across examples and schemas.
**Version 2.8.0: 29/06/2023**
> - Added the new Characteristics API as part of the Engage product offering.
**Version 2.7.9: 22/06/2023**
> - Updated __Retrieve Forecasted Transactions V1__ to show descriptive deprecation notice.
**Version 2.7.8: 19/06/2023**
> - Updated descriptions for Payments related endpoints.
**Version 2.7.7: 07/06/2023**
> - Updated response parameters for __Ingest First Party Data__ endpoints.
**Version 2.7.6: 01/06/2023**
> - Updated optional headers for __Reconfirm Consent__ endpoint to include `X-Customer-Ip-Address`.
**Version 2.7.5: 22/05/2023**
> - Updated the description and examples for the __Retrieve Balances Over Time__ and __Retrieve Balances Over Time By Account__ endpoints.
> - Updated the description and examples for the __Retrieve Transactions V2__ endpoint.
> - Updated __Retrieve Accounts__ to show descriptive deprecation notice.
> - Updated __Retrieve Accounts V2__ response HTTP codes, example transaction ID, `provider` query parameter description.
**Version 2.7.4: 19/05/2023**
> - Updated the description for the __Ingest Transactions V2__ endpoint.
**Version 2.7.3: 18/05/2023**
> - Updated the __Retrieve Authorisation Gateway URL (v2)__ endpoint with a new enable_async_connect option.
> - Updated the __Ingest Transactions V2__ request examples.
**Version 2.7.2: 18/05/2023**
> - Updated the description for the __Reconfirm Consent__ endpoint.
**Version 2.7.1: 16/05/2023**
> - Added documentation for __Retrieve Auth Tokens__ endpoint.
**Version 2.7.0: 11/05/2023**
> - Adds two new endpoints: __Create Customers V3__ and __Create Customers V3 (Batch)__.
> - Introduces the concept of Hosted Customers, which makes Customer Secrets optional on all endpoints which previously required them.
**Version 2.6.2: 05/05/2023**
> - Documented default to from case in __Retrieve Financial Products V2__ and __Retrieve Financial Products__.
> - Fixed documentation for get customers endpoints
> - Fixed documentation for put customer context endpoints
**Version 2.6.1: 27/04/2023**
> - Deprecated __Retrieve Financial Products__.
> - Corrected sample Financial Products in __Retrieve Financial Products V2__.
**Version 2.6.0: 25/04/2023**
> - Added new __Retrieve Categories V2__ endpoint.
> - Added new __Retrieve Available Categorisation Models V2__ endpoint.
> - Deprecated __Retrieve Categories__.
> - Added `models.categorisation` field to _Customer Context_ models.
**Version 2.5.3: 20/04/2023**
> - Updated __Retrieve Category Totals__ X-From and X-To parameter descriptions and endpoint description.
> - Updated __Retrieve Merchant Totals V2__ X-From and X-To parameter descriptions.
> - Updated __Retrieve Benefits Totals__ X-From and X-To parameter descriptions.
> - Removed __Retrieve Merchant Totals V1__ following deprecation period.
**Version 2.5.2: 19/04/2023**
> - Added `format` query parameter to __Retrieve Categories__.
**Version 2.5.1: 30/03/2023**
> - Fix income types for __Retrieve Income Transactions V2__.
**Version 2.5.0: 28/03/2023**
> - Deprecated __Retrieve Financial Forecast__.
> - Deprecated __Create Transaction Rule(s)__.
> - Renamed __Retrieve Upcoming Transaction__ endpoints (V1 and V2) to __Retrieve Forecasted Transactions__.
> - Renamed __Recategorise Transaction__ endpoints (V1 and V2) to __Correct Transaction Categories__.
> - Fix documented required fields for __Recategorise Transaction V1__.
**Version 2.4.0: 24/03/2023**
> - Deprecated __Retrieve Accounts__.
> - Finalised __Retrieve Accounts V2 (beta)__ to production release as __Retrieve Accounts V2__.
> - Finalised __Retrieve Account By ID V2 (beta)__ to production release as __Retrieve Account By ID V2__.
> - Finalised __Retrieve Balances Over Time (Beta)__ to production release as __Retrieve Balances Over Time__.
> - Finalised __Retrieve Balances Over Time By Account (Beta)__ to production release as __Retrieve Balances Over Time By Account__.
**Version 2.3.9: 21/03/2023**
> - Update merchant descriptions & required fields for **Retrieve Subscriptions**
> - Standardised description used for dates in __Retrieve Merchant Totals V2__.
> - Standardised description used for dates in __Retrieve Income Transactions V1__.
> - Standardised description used for dates in __Retrieve Income Transactions V2__.
> - Standardised description used for dates in __Retrieve Loan Transactions__.
> - Standardised description used for dates in __Retrieve Debt Collection Transactions__.
> - Standardised description used for dates in __Retrieve Benefits Transactions__.
> - Standardised description used for dates in __Retrieve Benefits Totals__.
> - Standardised description used for dates in __Retrieve Financial Products__.
> - Standardised description used for dates in __Retrieve Subscriptions__.
> - Standardised description used for dates in __Retrieve Upcoming Transactions V1__.
> - Standardised description used for dates in __Retrieve Salary Information__.
**Version 2.3.8: 21/03/2023**
> - Update amount descriptions
**Version 2.3.7: 20/03/2023**
> - Fix the docs for **Retrieve Money Management** correcting the category names for some warning types.
> - Remove the deprecated `large_expense` and `high_balance` warnings from **Retrieve Money Management**.
**Version 2.3.6: 16/03/2023**
> - Deprecated __Initiate Energy Payments Discovery__ and __Retrieve Energy Payments__
**Version 2.3.5: 13/03/2023**
> - Updated holder and holders fields on __List Accounts V2 (beta)__ and __Retrieve Account By ID V2 (beta)__.
**Version 2.3.3: 13/03/2023**
> - Document `provider_redirect_url` field for **Create Single Payment**
**Version 2.3.2: 13/03/2023**
> - Document `reconfirm_consent_redirect` field for **Retrieve Authorisation Gateway URL (v2)**
> - Added the `processor` field to the response from __Retrieve Income Transactions V2__
**Version 2.3.1: 09/03/2023**
The changes in this release carry no change to URLs, this is purely the name of the endpoint.
> - Renamed __Fetch Balance Actionable Insights (Beta)__ to __Retrieve Balance Actionable Insights (Beta)__
> - Renamed __List OB Providers__ to __Retrieve OB Providers__
> - Renamed __List Customer Consents__ to __Retrieve Customer Consents__
> - Renamed __List Categories__ to __Retrieve Categories__
> - Renamed __Fetch Financial Data__ to __Retrieve Financial Data__
> - Renamed __List Accounts__ to __Retrieve Accounts__
> - Renamed __List Transactions__ to __Retrieve Transactions__
> - Renamed __List Transactions V2__ to __Retrieve Transactions V2__
> - Renamed __List Accounts V2 (beta)__ to __Retrieve Accounts V2 (beta)__
> - Renamed __Balances Over Time (Beta)__ to __Retrieve Balances Over Time (Beta)__
> - Renamed __Balances Over Time By Account (Beta)__ to __Retrieve Balances Over Time By Account (Beta)__
> - Renamed __Affordability Report__ to __Retrieve Affordability Report__
> - Renamed __Affordability Transactions__ to __Retrieve Affordability Transactions__
> - Renamed __Get Financial Products__ to __Retrieve Financial Products__
> - Renamed __List Providers__ to __Retrieve Providers__
> - Renamed __List Single Payments__ to __Retrieve Single Payments__
> - Renamed __List Standing Orders__ to __Retrieve Standing Orders__
> - Renamed __List Scheduled Payments__ to __Retrieve Scheduled Payments__
> - Renamed __List Components__ to __Retrieve Components__
**Version 2.3.0: 07/03/2023**
> - Added new __Get Financial Products V2__ endpoint.
**Version 2.2.0: 28/02/2023**
> - Added a new __Balances Insights__ beta endpoint to the new Actionable Insights API. Not subject to breaking change restrictions.
**Version 2.1.1: 15/02/2023**
> - Corrected documented response descriptions and examples for __Get Financial Products__
**Version 2.1.0: 02/02/2023**
> - Added a new __List Accounts V2 (beta)__ and __Retrieve Account By ID V2 (beta)__ beta endpoints within the Financial Data API.
**Version 2.0.4: 31/01/2023**
> - Fix the docs for **List Transactions V2** correcting the date format in the example response.
> - Fix the docs for **Get Financial Products** correcting the expected response data structure.
> - Fix the docs for **Balances Over Time By Account (Beta)** correcting the endpoint URI.
**Version 2.0.3: 27/01/2023**
> - Fix the docs for **Retrieve Income Transactions V2** line with fixes for average statistic calculation.
**Version 2.0.2: 23/01/2023**
> - Make various spelling and grammar corrections to the Financial Review API docs, and additionally specify that the Financial Review API date ranges are to be received as GET parameters rather than headers.
**Version 2.0.0: 23/01/2023**
> - This major release not only showcases a new look and feel for Bud's API docs, but also some fairly significant changes to the structure of the endpoints across the platform. In a nutshell, Bud's Connect API (formally Open Banking Aggregation API) has a simplified structure with the retrieve data endpoints moving into a dedicated **Financial Data** section. In addition, the various insights endpoints have been broken down to provide a more simplified structure within the **Financial Insights** section.
> - \[**BREAKING**\] Bud's List Transactions (**POST** _/v1/open-banking/transactions_) has now been deprecated given the onsight of the new **List Transactions V2** endpoint (**POST** _/financial/v2/transactions_). Given the number of clients using the V1 endpoint, Bud has increased the deprecation window to six months. As a result, **all support will cease for the V1 List Transactions endpoint on the 1st of August 2023**. Please complete your migration before that date and contact your Bud account manager for further details and any help planning your migration.
> - Bud's Create Customers (**POST** _/v1/customers_) has now been deprecated. Support for this endpoint will continue, however we recommend clients to mirgate to V2 when possible.
**Version 1.22.3: 18/01/2023**
> - Improvements to __Ingest Transactions V2__ and __Ingest Transactions Task Status__ examples.
> - Removed the `provider` field from the __Ingest Transactions V2__ request payload.
> - Consolidate the List Accounts, V1 List Transactions endpoint and Remove OB Provider endpoints into the Financial Data API (to sit alongside the new V2 List Transactions endpoint).
**Version 1.22.2: 12/01/2023**
> - \[**BREAKING**\] _Balances Over Time_ and _Balances Over Time By Account_ beta endpoints now provide pending and booked balances. Please note this has changed the structure of the response. Please note, as these are beta endpoints, normal deprecation rules don't apply.
**Version 1.22.1: 10/01/2023**
> - General bug fixes and improvements across examples and schemas
**Version 1.22.0: 21/12/2022**
> - Bud is looking to undergo some major improvements to the code base of its Rent Recognition service throughout 2023 in order to bring it in line with the other services on the Bud platform. As a result, Bud has removed the current Rent Recognition service from its API documentation. For further details on when the new Rent Recognition service will be available, please contact sales@thisisbud.com or your relevant Bud account manager.
**Version 1.21.1: 15/12/2022**
> - Fix for Ingest Transactions V2 sync response
> - Fix for connect and refresh webhook status field
**Version 1.21.0: 15/12/2022**
> - Added a new __Balances Over Time__ and __Balances Over Time By Account__ beta endpoints within the Financial Data API.
> - Released __List Transactions V2__ with some additional examples added (the previous beta endpoint __List Transactions (beta)__ has now been removed).
> - Released the new Ingest Transactions V2 endpoint that enables synchronous processing for smaller payloads and also follows the latest schema for the List Transactions V2 endpoint.
**Version 1.20.10: 06/12/2022**
> - Updates to the __Transactions__ list endpoint (beta) examples, and added enrichments for `location` and `transaction_types`
**Version 1.20.9: 30/11/2022**
> - Updates to the __Transactions__ list endpoint (beta) which includes renaming the `cdi` field to `credit_debit_indicator`,
adding the transaction `processor` enrichment, the transaction `status` field and improvements across examples.
> - Added consent_id field to __Initiate Provider Authorisation__ endpoint to create authorisation URLs for a specific consent by sending the consent ID in the initiating request.
**Version 1.20.8: 15/11/2022**
> - General bug fixes and improvements across examples and schemas
**Version 1.20.7: 08/11/2022**
> - Added a new __Recategorise Transactions V2__ endpoint within the Submit Corrections API.
**Version 1.20.6: 07/11/2022**
>- Added a new field `customer_context` to the __Create Customers V1__ and __Create Customers V2__ endpoints,
along with new __Retrieve Customer Context__ and __Update Customer Context__ endpoints.
The Customer Context allows for the creation of a better user experience based on better knowledge of the customer themselves.
**Version 1.20.5: 01/11/2022**
> - General bug fixes and improvements across examples and schemas
> - Updates to the __Code Ids table__, with a full list of connect error codes
> - Added schemas for two new webhook callbacks for connect and refresh tasks.
> - Add payments `provider_types` field
**Version 1.20.4: 28/10/2022**
> - Added a new __Retrieve Authorisation Gateway URL__ and __Retrieve Authorisation Gateway URL (v2)__ response code.
**Version 1.20.3: 18/10/2022**
> - General bug fixes and improvements across examples, schemas, endpoints descriptions, names and sectioning titles.
**Version 1.20.2: 13/10/2022**
> - Added a new __Retrieve Upcoming Transactions V2__ endpoint within the Transactions Insights API.
**Version 1.20.1: 04/10/2022**
> - General bug fixes and improvements across examples, schemas, endpoints descriptions, names and sectioning titles.
**Version 1.20.0: 03/10/2022**
> - Added a new Financial Data API, containing a new __Transactions__ list endpoint (beta).
**Version 1.19.0: 30/09/2022**
> - Added a new __Reconfirm Consent__ endpoint within the Manage OB Connections API.
> - Added a new field to the V2 Open Banking Authorisation Gateway URL endpoint. The endpoint
allows clients to direct customers to the reconfirmation of consent journey, where customers can
extend their consent by 90 days.
**Version 1.18.1: 26/09/2022**
> - General bug fixes and improvements across examples, schemas, endpoints descriptions, names and sectioning titles.
**Version 1.18.0: 16/09/2022**
> - Added a new __Subscriptions__ endpoint within the Transactions Insights API.
**Version 1.17.0: 06/09/2022**
> - Added a new data field to the Retrieve Refresh Status endpoint as part of Bud's Connect (OB
Aggregation) API. The field - `has_new_transactions` describes whether any new transactions have
been obtained as part of the latest refresh, thus providing details on whether you as the Client
are required to fetch the latest transacitons for that customer.
> - Deprecated __Retrieve Merchant Totals V1__ in favour of the new __Retrieve Merchant Totals V2__ endpoint.
> - Added _Buy Now, Pay Later_ support to the __Get Financial Products__ endpoint, identified by
the enum value `bnpl`.
**Version 1.16.2: 16/08/2022**
> - Included a new query parameter within the List Consents endpoint to allow clients
to view all consents, i.e. those that have been expired/revoked, and those that are
awaiting authorisation (as well as those that are active).
> - General bug fixes and improvements across examples, schemas, endpoints descriptions, names and sectioning titles.
**Version 1.16.1: 11/08/2022**
> - General spelling corrections and improvements across examples
**Version 1.16.0: 01/08/2022**
> - \[**BREAKING**\] The `X-From` and `X-To` date fields will now follow the date format of YYYY-MM for `/v1/affordability/spending-groups`. **Please note that the current date format for `X-From` and `X-To` will no longer be supported in three months time on the 1st November 2022**. All clients with existing integrations will be contacted via email by their relevant account manager to inform them of this change. This should provide clients with enough time adjust their integration before the change coming into force. Please contact `help@thisisbud.com` or your account manager if you have any questions, issues or concerns relating to this update.
**Version 1.15.2: 22/07/2022**
> - General spelling corrections
**Version 1.15.1: 18/07/2022**
> - General bug fixes and improvements across examples, schemas, endpoints descriptions, names and sectioning titles.
**Version 1.15.0: 29/06/2022**
> - \[**BREAKING**\] The `period` field will have new enum values when calling the `/v1/regular-transactions` and the `/v1/future-transactions` endpoints. **Please note that this change will only come into effect in three months time on the 5th October 2022**. All clients with existing integrations will be contacted via email by their relevant account manager to inform them of this change. This should provide clients with enough time adjust their integration before the change coming into force. Please contact `help@thisisbud.com` or your account manager if you have any questions, issues or concerns relating to this update.
> - Fixed some inaccuracies with the __Signal Money Management__ docs.
**Version 1.14.0: 27/06/2022**
> - Added a new __Affordability Report__ endpoint within the Financial Review API.
> - Added a new __Affordability Transaction__ endpoint within the Financial Review API.
**Version 1.13.2: 22/06/2022**
> - Fixed doc issues with some __Signal__ warnings (__Money Management__ `regular_monthly_income_change` and __Financial Insights__ `gambling_threshold`)
**Version 1.13.1: 22/06/2022**
> - Fixed issues with doc site dependencies
**Version 1.13.0: 21/06/2022**
> - Added a new __Debt Collection Finder__ endpoint within the Transaction Insights section.
> - Added a new __Product Finder__ endpoint within Transaction Insights which creates a summary of a customer's financial products using their transaction history.
> - Added Parties to the __List Accounts__ endpoint in the Manage OB Data section
**Version 1.12.2: 24/05/2022**
> - General bug fixes and improvements across examples, schemas, endpoints descriptions, names and sectioning titles.
> - Added a new __Income Finder V2__ endpoint within the Transaction Insights section.
> - Added a new __Loans Finder__ endpoint within the Transaction Insights section.
**Version 1.12.1: 05/05/2022**
> - Moved __Benefits Finder__ endpoint into the correct section - Transaction Insights.
**Version 1.12.0: 26/04/2022**
> - Added a new __Benefits Finder__ endpoint within the Transaction Insights section that provides details around any benefit specific transactions a customer might have within their connected accounts.
> - Fixed typos.
**Version 1.11.3: 14/03/2022**
> - Deprecated __Enrich Transaction__ endpoints from the Ingest and Enrich API suite.
> - General improvements across examples, schemas, endpoints descriptions, names and sectioning titles.
**Version 1.11.2: 31/01/2022**
> - Corrected syntax for Custom Signal endpoints.
> - Fixed typos.
**Version 1.11.1: 27/01/2022**
> - Added a better description to the Recategorisation (Customer Corrections) endpoint.
> - Fixed typos.
**Version 1.11.0: 05/01/2022**
> - Added a new __Income Finder__ endpoint within the Transaction Insights section that provides details around any income specific transactions that a customer might have within their connected accounts.
> - Detailed the payload of the callbacks (webhooks) sent to the relevant Client webhook URL when (i) an Open Banking Synchronisation task completes (i.e. after either a Connect or Refresh request has been made by the Client); and (ii)
when the status of a Payment (single, scheduled or stand order) has either completed or failed.
> - Included a new 400 response example in the Get Authorisation Gateway URL and Initiate Refresh endpoints (within Bud's OB Aggregation API) to detail the response when the selected provider is currently in maintenance mode.
> - Corrected the documentation of the List Accounts endpoint to ensure that the `account_type` field is shown as nullable.
**Version 1.10.1: 22/11/2021**
> - Added a new __Custom Signals__ endpoint within the Signal API that allows you to segment and identify customers based on custom criteria.
**Version 1.10.0: 28/10/2021**
> - Added a new __Delete Provider Data__ endpoint.
> - Deprecated __Retrieve Authorisation Gateway URL__ endpoint following the introduction of the new `/v2/open-banking/authorisation-gateway-url` endpoint.
> - Moved `/v1/energy-switching/energy-payments` & `/v1/energy-switching/energy-payments/{task_id}` endpoints from Energy Switching API to the Insights API.
> - Deprecated remaining endpoints within the __Energy Switching API__.
> - Deprecated all endpoints within the __Mortgage API__.
> - Deprecated all endpoints within the __Home Insurance API__.
> - Deprecated all endpoints within the __Broadband API__.
**Version 1.9.0: 14/10/2021**
> - Addition of a new endpoint `/v2/open-banking/authorisation-gateway-url` to allow clients to use an updated
Bud Connect flow, allowing their customer's to go through a new Account Connection journey. The v2 journey is
highly configurable via the use of different flags within the request payload.
**Version 1.8.3: 06/10/2021**
> - General bug fixes and improvements across examples, schemas, endpoints descriptions, names and sectioning titles.
**Version 1.8.2: 16/09/2021**
> - Altered the List Consents endpoint to now take in an optional `X-Customer-Secret` field within the request headers. If done so, each consent object will now return a list of `account_ids` associated with the consent object in addition to a date denoting the date a which a refresh was successfully completed for that given consent object.
**Version 1.8.1: 07/09/2021**
> - Added a new Submit Authorisation Codes endpoint for use within the Payments flows when using Bud as a technical service provider.
**Version 1.8.0: 01/09/2021**
> - Deprecated __Warnings__ endpoint within the Signal API
> - Added a new __Money Management__ endpoint within the Signal API that allows clients to provide more detailed information regarding a customer's financial situation.
> - Added a new __Customer Characteristics__ endpoint within the Signal API that allows clients to profile based on a customer's transactions.
> - Added a new __Financial Insight__ endpoint within the Signal API that allows clients to understand a customer's overall financial situation and affordability.
**Version 1.7.10: 06/08/2021**
> - Updated the List Transaction Response schema to detail the addition of the new carbon tracker enrichment field.
**Version 1.7.9: 03/08/2021**
> - The `customer_secret` attribute is now a required attribute on the POST Ingest Accounts endpoint.
> - Updated the List Transaction Response schema to detail those fields that are required and/or nullable.
> - Created a new Create Transaction Rule(s) endpoint that allows client to set a value of the `client_label` attribute against a set of customer transactions which adhere to the rules specified in the request payload.
> - Updated API Overview table in the introduction to include latest product set.
> - Removed deprecated Financial Assistant endpoints.
**Version 1.7.8: 28/05/2021**
> - Addition of some optional fields to the POST Retrieve Authorisation Gateway URL endpoint. The additional fields allow clients to specify: (i) a single provider, effectively skipping the select provider screen in the customer UI; (ii) a list of providers, allowing clients to configure the list of providers shown to the customer on the select provider screen; and (iii) filter the provider list shown to the customer by the type of provider (e.g. business or personal). In addition, a `connect_more_accounts_button` flag can be configured to show the customer a button at the end of the connection flow that will allow them to connect to another provider without having to return to the client application.
**Version 1.7.7: 15/04/2021**
> - Updated the examples within Bud's KYC endpoints to make them more usable against Bud's sandbox environment.
> - Addition of a new GET `/v1/open-banking/account-access-consents` endpoint to allow clients to query the active consents against a given customer (in relation to Bud's OB Aggregation service).
**Version 1.7.6: 17/03/2021**
> - Addition of a new "Regular Payment Changed" Insight to the Warnings Endpoint (that forms part of Bud's Signal Product).
> - Bugfix: addition of the required `mobile_phone_number` field to the request payload of the Switch Supplier endpoint within the Energy Switching API to align to the implementation of the API itself.
> - Bugix: the format of the `annual_spend.amount` field within the request payload of the kWh Estimation endpoint now states that is should be a number (as opposed to a string) to align to the API itself.
**Version 1.7.5: 10/02/2021**
> - Fixed bug in the List Accounts endpoint for Bud's OB Aggregation service - the response data object now details all the returned fields as expected.
> - Removed the deprecated List Account Balances endpoint from the documentation entirely.
> - Added a new __Ingest Accounts__ endpoint within the Enrichment API that allows clients to provide more detailed information regarding a customer's account.
**Version 1.7.4: 25/01/2021**
> - Addition of a Know Your Customers (KYC) API allowing clients to perform KYC checks on businesses or their customers.
> - \[**BREAKING**\] The `X-Customer-Secret` is now a required field within the headers of the `/v1/open-banking/authorisation-gateway-url` endpoint. **Please note that this change will only come into effect in three months time on the 1st of May 2021**. All clients with exisitng integrations will be contacted via email by their relevant account manager to inform them of this change. This should provide clients with enough time adjust their integration before the change coming into force. Please contact `help@thisisbud.com` or your account manager if you have any questions, issues or concerns relating to this update.
**Version 1.7.3: 11/01/2021**
> - Addition of the changelog to the api docs, and further information around updates and versioning.
> - Documentation Bug Fix: `redirect_url` field is now shown as required within the **POST** `/v1/open-banking/authorisation-url` endpoint. This affects those clients using Bud's TSP Aggregation Service.
**Version 1.7.2: 18/12/2020**
> - Introduction of a new payment service within Bud's Payment API. Clients are now able to initiate __Scheduled Payments__ from Bud's Payments service. The scheduled payments service is available to those clients using Bud as a TPP (i.e. via Bud Pay) and as a TSP.
> - Bud have now released their __First Party Transactions Ingestion__ endpoint. This allows clients to simply post Bud some of their customer's transactions, which will then be run through each of Bud's enrichment and insights services and then stored securely. This opens up Bud's plethora of Insights services, Signal, and Financial Review to those clients with first-party transactional data.
**Version 1.7.1: 06/12/2020**
> - Few changes to the Payments endpoint responses, including:
> - the GET providers endpoint, `required_actions` field now becomes an array (as opposed to an object) and is populated with string enums which are now clearly described in the schema.
> - the response of the create Single Payment and Standing Order endpoints now includes a `required_action` field as opposed to required_actions (since there will only ever be one next required action). If this field appears within the response then clients must take another action in order to complete the payment flow.
> - the payment status endpoint also now includes the `required_action` field, which if not null, clearly indicates that the client is required to perform the necessary action in order for the payment to complete.
> - updated the payment service enums within the response of the GET providers endpoint, since each provider can now potentially offer `domestic-single-payment`, `domestic-standing-order` and (soon to be) `domestic-scheduled-payment` services.
> - Added extra information within the description of various Rent Recognition endpoints. This should provide clients with a much clearer understanding of which endpoints are needed and why in order to integrate the entire RR journey.
**Version 1.7.0: 27/11/2020**
> - Added a new POST /v2/customers endpoint that allows clients to create up to 200 customers in a single request.
> - \[**BREAKING**\] Deprecated Financial Assistant endpoints (warnings / trends / forecast) and introduced these endpoints under a new API called Signal with updated urls and operation_ids.
> - Altered description of the OB Aggregation TPP Retrieve Authorisation Gateway URL to include for information into its usage.
> - Introduction of a new set of Payments based endpoints allowing customers to set up and authorise standing orders from one of Bud’s supported providers. This comes in the form of:
> - a new TPP endpoint, where clients can now request a new Bud Pay URL to allows customers to set up a new standing order; and
> - a new set of TSP endpoints, allowing clients to integrate Bud APIs to allow their customers to initiate standing orders.
**Version 1.6.5: 10/09/2020**
> - Addition of the `period` field to the __GET__ `/v1/salary` endpoint to provide an indication into any regulatory associated with a predicted salary transaction.
**Version: 1.6.4: 06/08/2020**
> - \[**BREAKING**\] Deprecated the use of `bank_name` in relevant schemas within Bud’s OB Aggregation API in favour of of the field `provider`
> - Updated Affordability API title to Financial Review API and provided an updated description of the API.
> - Updated the product table within the introduction to reflect new titles and descriptions across Bud’s API services.
**Version: 1.6.3 - 20/07/2020**
> - Added a new endpoint for the OB Aggregation TSP flow - __POST__ `/v1/open-banking/authorisation-codes`. It allows clients to send back the parameters they receive from the bank once the customer has completed the authorisation process. This allows Bud to match the state to the relevant task id, and also provides the relevant code that will allow Bud to start fetching the customer’s data from the provider.
**Version: 1.6.2 - 16/07/2020**
> - Addition of international updates to payments APIs
> - Updated energy switching meters example to ensure that it will return meter information for the address given in the example.
**Version: 1.6.0 - 15/06/2020**
> - Financial Assistant service added to the Insights API. This includes three brand new endpoints that help customers to better manage their financial world.
> - _Retrieve Warnings_: provides a list of potential scenarios where a customer might suffer some financial expense (e.g. in their overdraft, cannot cover bills, late payment and late income)
> - _Retrieve Trends_: provides the key trends associated with a customer’s transactional data broken down by month
> - _Retrieve Forecast_ - provides a list of the regular and predicted transactions over a given period, noting whether they are booked, pending or predicted.
> - Affordability Service added to the documentation, including a brand new endpoint to help clients to assess their customers affordability. The _Create Spending Groups_ endpoint allows clients to create their own custom group, e.g. Discretionary Spend, where they can select which of Bud’s categories and/or subcategories will make up the group. All transactions for that customer assigned to the categories/subcategories within the group will be bucketed up and the client will be able to see the total income and expenditure in those categories over a given period of time.
**Version: 1.5.3 - 22/05/2020**
> - Added Payments: List Payment Status endpoint in order to retrieve paginated details of multiple payment ids based on header filters
> - General bug fixes and improvements across examples, schemas, endpoints descriptions, names and sectioning titles.
**Version: 1.5.0 - 08/04/2020**
> - Addition of Bud’s Payment Initiation API. The endpoints provide clients with the functionality to allow their customers to make payments from one of their bank accounts, to a chosen recipient. In their first iteration, customers are able to authorise a single payment from one of their UK based bank accounts to another UK bank account.
> - Addition of a Category Totals endpoint. The endpoint allows clients to retrieve the total amount of money that is moving into and out of their customers' connected bank accounts, broken down by transaction category. The endpoint breaks the totals down by both tier 1 and tier 2 type categories (as is provided by Buds dual layered categorisation engine).
> - Acceptance of a new transaction schema format for all 1st Party Enrichment Endpoints. All of Bud’s first party data enrichment endpoints (i.e. __POST__`/v1/categorise/double-cat`, __POST__`/v1/regular-payments`, __POST__`/v1/merchants`) are now able to accept the transaction format outputted by TrueLayer. This makes it even easier for those clients who are using TrueLayer as an aggregator to get the use of Bud’s enrichment services.
# Authentication
contact:
name: Bud Support
email: help@thisisbud.com
url: https://www.thisisbud.com/
x-logo:
url: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATAAAABuCAQAAAAKAYdLAAAACXBIWXMAAC4jAAAuIwF4pT92AAAAB3RJTUUH4wQDDggcbXcx7wAABeJJREFUeNrt3W2IFVUcx/HvXRW1VdQedy1bZVfoYX0osVQyfSGElKbRA5oFIaIlhAkWUYm6gvqqDMHMoBeKlhayCCZC2AMRPay7aJrSZmauZhQqaj7t7u1Fi965987s7D1n7pk7/j73zX2Y85//mXt2Zu45Z2ZBREREREREREREREREREREREREREREREREREREREREREREREREROIiZSFGH+YxgsOs5U/X1bFiPDPpQT3bu1DmcaZyg+vErWpjD+s47zoN6Mte0qRJc4Iq18lYMJv2jvosD11mRUeJpD32UO7664BFGQl94DoZY704fbU2rQwKVWYwbc6bQlSPBaYbtMz4K7nP53lpGkK/q8+7MTxUmeEWtmJcGX+j5psmM0I3l9vCirKAV36OuE46QsbfaHL/9opnL9tcpxBf3V0nkAgzWMRj9HadhrH+3Gk7pBqYDZdY3oXfnHE2gc1U2gyoQ6Rk+pKZdgOqgYnXF7TYDGe3gcWgW85QH9cJxMAVm8HsNrBqhhV1U9g33XUCzo1gsM1wdhtYio8ZWsytYdksFrpOwbGhbLYb0PavyLs5wA+c9v28lRa+Zzt/+y5RwwKqaOCdgCjZRvEit/A1a7jou8xwJjOMAb7D+ylqqCmw1imeZ0oCBrv7Mzp+/QofFTDCdZG13Jw3Wi1nOpbZT9+QGUziUkeZ3T49z+P4pqCRuCkhM1jjfMwwqsdG182rsAaWJs0JxuWJ9knGEq+EzODHjDLTcj5NsbjgwehwDazm6vyL5D2MG5i7booKdjE25917M57XhoxUG1hmJUsjrmWtlVl18ZQ2DeCyH6ycT7kpIJ+wuQWVeZJXI69HcpsXHDQN4LajtZIlkcbvzWqn9St1R3nPNIT93wzt/MSZPO+nqKA65699Nos5FdHmgZkMzHnvIj9zLm9+Q7jd0nqP8VtkdSqWNppYxT+u08g+yW8OnKRXw4ac08hnPUscyvjkw5AZXM4os9jzyY6sdZ3h5YC++jLm0lrASf50T5krzEn0QbOLbB8in2FvwKfNPJczCXd0hLV7wPPqL8bybt691//aWWfhkPo2681PjZPDbgP7lYZOl1nNJs9rW4elXD2zfkK8wIFOy2w1XuuWyOpTkuw2sHOhlqrzvIqu59gbuYEdIcqcjSyb65SLX5EHOepgrbuKtJ6nHNQtxtx0U5xM8DoXMkez7K5xM7Tp4iS4WOvszvss5feSP9Fvo5EVnDDfHGJfpd157Y48xFRGmfaEaWcu/qqYZxpCDcxcqR8Mg9xlGkANzNz+BDcx4zEJNTBzv5gPCSeXTvJtmM+3PJqIKdNj6GE3pJsG5mIwOMp1ptnABgd1sq+G7ebnXZncHCKjG3+M1zpLTzMz7AZ00cBG5pmlFb3JmkQTSpPd21HZbWD9Qy21zPPK/zricNH6+B7mvZFreTpEtAFWt0dpsnoWZreBVTG+kyVS1GVN4/vDd9lJVIRY5yzfPdPlrPHHdTwYItr1bkLcTia8M1qPM9F3yRRjcuaYprNmHxzyfNbQyQlnGTM47ynhndFan7WuCywLODz35I2sC9DCXheZHBNpsXvZmu1fkZXs5rjPnPzb8hyAzrIzINr9HOBIwNXat+ZcleS1hame1714izc55jNvbVDBtz7pyWuJuI15P/tnx1F0UwzsQpprO5nil2KIQSZbqcspnwp57+iu2MQT1mMmhNue/MMR3xfwMi8VYRhnmJqXP/MG1lZwyVNMy9l/FR4tf/mdvB553Uz2sXFn+n1YaGCNBZZr5mH25by7xzCb3PKrmM+lgmK1BV4hdc0+2g2zjq8m1wlAOY1dvqXGKep87oZYzUmDW3Vs8+myuIf6Am6AsiT0Nljp/CYl0Twaze9ZaaN3u5w5jAy5L2ylhe/4nAu+S1Qwl+oCsrjCV2wM2KXfwSPUcmPIGv9LPZ91Ye1TEnEb80ztNLE+Dv8MS0RERERERERERERERERERERERERERERERERERERERERERERERERs+Q/rhi5WauEgfQAAAABJRU5ErkJggg==
servers:
- url: https://api-sandbox.thisisbud.com
tags:
- name: Authentication
description: |
Endpoints related to gaining access to the Bud platform via OAuth2 authentication.
x-displayName: Authentication
x-traitTag: true
- name: OAuth2
x-displayName: OAuth2
description: |
Retrieve and manage access and refresh tokens to authenticate to the Bud platform via OAuth2 protocol.
- name: Connect API
description: |
These endpoints handle the connections to Open Banking providers (ASPSPs) and the ingestion of first party transaction data. Bud manages all of the connections to each of the individual ASPSPs and enables access to all of the providers via a single set of API endpoints.
Bud currently supports three methods of connecting your customers data to the Bud platform:
1. You can use the [__Bud Connect__](#operation/v2_ob_authorisation_gateway_url_post) endpoint which returns a link to Bud’s pre-built Open Banking customer connection journey that can be configured to your brand.
2. If you have your own license you can choose to host the Open Banking customer connection journey yourself, using [Bud's APIs](#operation/open_banking_authorisation_url_post) to create the connection. __If you are an agent of Bud but feel that your application could benefit from a more native feel please talk to your Bud Account Manager or email help@thisisbud.com for further details.__
3. If you already have transactional data that you’re looking to enrich, you can use Bud’s [Ingest Endpoints](#tag/Ingest-Data) to push your data onto the Bud platform without needing your customers to connect their accounts via Open Banking.
Note: a number of the calls within this service are asynchronous, and as such, follow a pattern of sending a request and responding with a task ID. This task ID can then be tracked, allowing for a more efficient, cross network implementation.
x-displayName: Connect API
x-traitTag: true
- name: Create a Connection
x-displayName: Create a Connection
description: |
Create a new connection to an Open Banking provider by using either: (i) Bud's configurable frontend UI (__Bud Connect__), built to maximise conversion; or (ii) Bud's individual API endpoints to help you build your own connect flow.
- name: Manage a Connection
x-displayName: Manage a Connection
description: |
Different endpoints that allow to to manage an existing customer connection. This includes the ability to:
(i) Refresh the data associated with a given connection, pulling in the latest account
information into the Bud platform;
(ii) Renew an existing consent by-passing the need to go through Strong Customer
Authentication (SCA) with their bank;
(iii) Revoke a consent, removing the ability for Bud to fetch any further data associated
with that consent.
- name: Ingest First Party Data
x-displayName: Ingest First Party Data
description: |
Initiate the asynchronous process of pushing a customer's account information (i.e. first party data) onto the Bud platform. These asynchronous requests create a task to store the given accounts or transactions against the specified customers. The Task ID returned by this request can be used to verify the current status of the process.
- name: Customers API
description: |
The Customers API allows for the manipulation of a client's "Customers" as registered on the Bud platform. The API is built around resource-oriented URLs, returns JSON-encoded responses, uses standard HTTP response codes and authentication.
x-displayName: Customers API
x-traitTag: true
- name: Manage Customers
x-displayName: Manage Customers
description: |
Manage the number of customers registered onto the Bud platform.
- name: Enrichment API
description: |
Enrich transactional data you already hold, or have aggregated through Open Banking, using Bud's core enrichment services.
x-displayName: Enrichment API
x-traitTag: true
- name: Enrichment Resources
x-displayName: Enrichment Resources
description: |
Obtain greater context to Bud's enrichment services.
- name: Enrichment Totals
x-displayName: Enrichment Totals
description: |
Breakdown your customer's income and expenditure based on Bud's enrichments to help orientate their financial world.
- name: Financial Data API
description: |
These endpoints handle the aggregation and retrieval of financial data. They are designed to be generic across a range of ingestion sources and regions.
x-displayName: Financial Data API
x-traitTag: true
- name: Retrieve Financial Data
x-displayName: Retrieve Financial Data
description: |
Retrieve a customer's financial data from a range of sources.
- name: Manage Financial Data
x-displayName: Manage Financial Data
description: |
Manipulate Transactions held on the Bud platform by removing data, submitting corrections, or adding tags through different rulesets.
- name: Correct Financial Data
x-displayName: Correct Financial Data
description: |
Manipulate Transactions held on the Bud platform by finding similar transactions and submitting corrections.
- name: Goals API
description: |
Endpoints related to managing savings goals and spending budgets.
x-displayName: Goals API
x-traitTag: true
- name: Spending Budgets
x-displayName: Spending Budgets
description: Spending budgets management API.
- name: Savings Goals V2
x-displayName: Savings Goals V2
description: Savings goals management API V2.
- name: Smart Finders API
description: |
Find information about spending, identify key transactions and create your own custom transaction labels to dig deeper into the data and build new services for customers.
x-displayName: Smart Finders API
x-traitTag: true
- name: Regular Payments Finder
x-displayName: Regular Payments Finder
description: |
Find information relating to any regularity found across certain groups of transactions within your customer's accounts.
- name: Income Finder
x-displayName: Income Finder
description: |
Find information regarding your customer's income.
- name: Loan Finder
x-displayName: Loan Finder
description: |
Find information regarding your customer's loans.
- name: Debt Collection Finder
x-displayName: Debt Collection Finder
description: |
Find information regarding your customer's debts.
- name: Product Finder
x-displayName: Product Finder
description: |
Find information regarding your customer's financial products.
- name: Subscription Finder
x-displayName: Subscription Finder
description: |
Find information regarding your customer's subscriptions.
- name: Intelligent Search API
description: |
Intelligent search provides an improved interface for customers to search & ask questions about their financial transactions.
x-displayName: Intelligent Search API
x-traitTag: true
- name: Transaction Search
x-displayName: Transaction Search
description: |
Allows customers to search & ask questions about their financial transactions.
- name: Assess API
description: |
These endpoints handle the origination of customer applications for the Assess
Dashboards. This use-case is designed for clients that wish to have an API
integration with the data that is available via said dashboards.
These endpoints facilitate a flow whereby:
- An application, associating a customer's name with their financial
information, can be created (and is visible in the dashboard).
- Customers can be given a URL to follow, which will allow them to connect up
their bank accounts.
- Customers' financial data and financial insights can be retrieved (via the
dashboard and via API).
- Application statuses can be managed (e.g. marked as reviewed/open) for
other users of the dashboard to see.
A key example of this being used is for loan applications: the Assess API
can be used to collect a customer's financial data, which can then be
retrieved and assessed (either using the API to pull in the data, or using
the dashboard to make manual decisions regarding the application status).
x-displayName: Assess API
x-traitTag: true
- name: Customer Applications
x-displayName: Customer Applications
description: |
Create, retrieve and manage financial applications for customers using the
Assess product. Applications created on this platform can be viewed using
the Assess Dashboard to observe application statuses.
- name: Customer Application Links
x-displayName: Customer Application Links
description: |
Create a link for a customer to follow, which will allow them to connect
their bank accounts and submit their financial data for the application.
- name: Aggregation Buckets
x-displayName: Aggregation Buckets
description: |
Manage virtual "buckets" for grouping and aggregating transactions by their
underlying categories.
Use this for retrieving financial data for customers of the Assess Dashboard
(where the `bucket_id` is `assess-dashboard`) as it appears in said dashboard.
- name: Retrieve Affordability Report V2
x-displayName: Retrieve Affordability Report V2
description: |
Breakdown your customer's transactions by fixed/flexible spend and discretionary vs non discretionary high-level totals.
Retrieve Affordability Report V2 endpoints are designed to closely reflect the assess dashboard aggregations/definitions.
- name: Retrieve Affordability Report
x-displayName: Retrieve Affordability Report
description: |
Breakdown your customer's transactions by fixed/flexible spend and discretionary vs non discretionary high-level totals.
- name: Retrieve Affordability Risk Insights
x-displayName: Retrieve Affordability Risk Insights
description: |
Retrieve a customer's report insights generated from their financial data. In contrast to the alert style actionable insights,
these insights should be used more as a summary.
- name: Payments API
description: |
These endpoints allow Bud's Clients to initiate (i.e. make) payments through the use of Open Banking Payment APIs.
Bud manages the connections to each of the payment providers, and serves these connections under a single set of API endpoints, enabling Bud's clients (and in turn their customers) to initiate a payment from one of these providers to a chosen recipient.
Bud currently supports two methods for initiating payments with available providers:
1. If you are not regulated to provide payment initiation services, or if you are regulated but do not wish to use
your own permissions, then use Bud's [TPP Initiation](#tag/TPP-Initiation) endpoints.
2. If on the other hand, your are regulated as an Payment Initiation Service Provider (PISP), then you are able to use Bud
as a Technical Service Provider (see [TSP Initiation](#tag/TSP-Initiation)).
x-displayName: Payments API
x-traitTag: true
- name: Initiate Payment - Bud license
x-displayName: Initiate Payment - Bud license
description: |
Authenticates and securely creates a new payment from a customer’s chosen account(s) using Bud's regulatory licence as a
[Third Party Provider (TPP)](https://www.openbanking.org.uk/providers/third-party-providers/) of Payment Initiation Services.
- name: Initiate Payment - Client license
x-displayName: Initiate Payment - Client license
description: |
Authenticates and securely creates a new payment from a customer’s chosen account(s) using your organisation's regulatory
permission as a Payment Initiation Service Provider (PISP).
- name: Manage Payments
x-displayName: Manage Payments
description: |
Manage payments to initiated through Bud's Payments API
- name: Characteristics API
description: |
The Characteristics API provides endpoints for retrieving specific characteristics that apply to an individual
Customer based on their financial data. The currently supported characteristics are:
| Characteristic | Description |
|:---------------|:---------------------------------------------------------------------------------------------|
| `credit_card` | Customer has made credit card repayments |
| `loan` | Customer has made loan repayments (excluding credit cards) |
| `overdraft` | Customer has paid overdraft fees |
| `saver` | Customer has savings transactions |
New characteristics will be released and added to this list without a breaking change notice.
x-displayName: Characteristics API
x-traitTag: true
- name: Retrieve Customer Characteristics
x-displayName: Retrieve Customer Characteristics
description: |
Retrieve Characteristics associated with an individual Customer based on their financial data.
- name: Insights API
description: |
These endpoints handle the retrieval of actionable insights for a customer. An actionable insight is an indicator of
the state of a customer's financial situation that could induce a change in behaviour.
x-displayName: Insights API
x-traitTag: true
- name: Retrieve Actionable Insights
x-displayName: Retrieve Actionable Insights
description: |
Retrieve a customer's actionable insights generated from their financial data.
- name: Custom Insights
x-displayName: Custom Insights
description: |
Understand and target messaging to your customers more effectively by defining your own custom insights.
- name: Frontend Widgets
x-displayName: Frontend Widgets
description: A collection of frontend widgets representing customer financial data.
paths:
/v1/oauth/token:
post:
tags:
- OAuth2
summary: OAuth2
description: |
This endpoint is used to create access and refresh tokens.
The access token is used as a bearer token to authenticate requests to Bud endpoints;
the refresh token is used to generate a new access token without the need to supply your client credentials again.
The access token usually expires after the `expires_in` time (in seconds) has elapsed.
However this is not guaranteed, so it is recomended to integrate such as to handle the `401` response code and refresh the token when it this response code is seen.
Refresh tokens typically expire after 24 hours, but this is not guaranteed.
> **🚧** Recognise the sensitive nature of access tokens. Implement appropriate security measures to prevent unauthorized access.
Related Guides:
- https://docs.thisisbud.com/docs/authentication
operationId: oauth_token_post
security:
- Basic: []
parameters:
- in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/x-www-form-urlencoded
- $ref: '#/components/parameters/ClientId'
- in: header
name: authorization
schema:
type: string
description: |
The `authorization` header is used to send the client credentials in the form of a base64 encoded string.
The format of the string is `client_id:client_secret`.
This is only required when retrieving an auth token and not whilst refreshing an auth token.
Example: `Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=`
example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
oneOf:
- title: When Retrieving an Auth Token
required:
- grant_type
properties:
grant_type:
type: string
enum:
- client_credentials
- title: When Refreshing an Auth Token
required:
- grant_type
- refresh_token
properties:
grant_type:
type: string
enum:
- refresh_token
refresh_token:
type: string
description: The `refresh_token` received when initially retieving an auth token.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveAuthTokenResponse'
example:
operation_id: oauth_token_create
data:
access_token: RJptkI22inJMLGmRvdUWUj02WA6cuV0P2cPAF1OkG5F2FAh41hkbGw26v419M7me4qCfsu4pZwfjxB6wOO42dJeTnTAv41C4CnR0Mkism1fwbg6trIo5lNixX1roWD4gZkG8W1Mp4cjaPWe41sc9S61Jmt6TvMgXJ3VRxqnSR9UVlaF7oeJPLwi7sHHcKuaiLrNflwEDE2aZNDVHqmNeiDFrY8GQAzNCQLevqkMKGDsnRtoD2EqX8YKu6G2z3Vr
token_type: Bearer
expires_in: 3600
refresh_token: XO9haFEajZaEqYY8wJUkdsVWG2b3r6jY1aXdsbhNtgmiz4K6e78hZt73kTQjuO57sVo8T6xHAjxk6Day0utTpHnXzUrKy7GSESsmxJoKzcCZeXdJCQLQvyXLSYMlMf3OZVpwcwJp7fnpCARdhmP0oLocSEnTSh60FBO2HQCnseFT6DgtSTsODbx8HC230epKAbkyOeGkC2gWQctXAFb1dNa8r1W8RzPWGe5a6wkAUH2rQiv7RjIA7Eoy663Sf9Q
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
examples:
Basic Auth Credentials Incorrect:
value:
operation_id: unknown
code_id: unknown
message: Unauthorised request
Basic Auth Missing:
value:
operation_id: oauth_token_create
code_id: failed_validation
message: could not extract basic auth headers
Grant Type Missing/Incorrect or Content Type missing:
value:
operation_id: oauth_token_create
code_id: failed_validation
message: could not extract basic auth headers
errors:
grant_type: grant_type must be one of [client_credentials refresh_token]
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: oauth_token_create
code_id: unauthorised
message: Unauthorised.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: oauth_token_create
code_id: forbidden
message: Forbidden.
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/v1/open-banking/providers:
get:
tags:
- Create a Connection
summary: Retrieve OB Providers
description: |
List the available account providers with their name, icon and maintenance status.
operationId: open_banking_providers_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/OBProvidersQueryTypeFilter'
- $ref: '#/components/parameters/OBProvidersQueryRegionFilter'
- $ref: '#/components/parameters/OBProvidersQueryScopesFilter'
responses:
'200':
description: List of providers available via Bud's Open Banking Aggregation APIs
content:
application/json:
schema:
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
$ref: '#/components/schemas/OBProvider'
metadata:
oneOf:
- $ref: '#/components/schemas/ResultsMetadata'
- type: object
nullable: true
example:
operation_id: open_banking_providers_get
data:
- provider: barclays
display_name: Barclays
maintenance_window:
start: 2019-08-07T11:48:00+0000
end: 2019-08-07T11:00:00+0000
maintenance_status: active
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: fd
display_name: first direct
maintenance_window:
start: 2019-08-07T11:48:00+0000
end: null
maintenance_status: active
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: halifax
display_name: Halifax
maintenance_window: null
maintenance_status: inactive
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: hbos
display_name: Bank of Scotland
maintenance_window: null
maintenance_status: inactive
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: hsbc
display_name: HSBC
maintenance_window: null
maintenance_status: inactive
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: lloyds
display_name: Lloyds
maintenance_window: null
maintenance_status: inactive
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: mns
display_name: Marks & Spencer
maintenance_window: null
maintenance_status: inactive
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: nationwide
display_name: Nationwide
maintenance_window: null
maintenance_status: inactive
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: natwest
display_name: Natwest
maintenance_window: null
maintenance_status: inactive
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: rbs
display_name: Royal Bank of Scotland
maintenance_window: null
maintenance_status: inactive
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
- provider: santander
display_name: Santander
maintenance_window: null
maintenance_status: inactive
icon: https://assets.thisisbud.com/example-icon
regions:
- GBR
mobile_only: false
metadata: null
'400':
description: Bad Request that fails validations on headers & payload
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
5XX:
description: An unexpected error occurred on the server side
/v2/open-banking/authorisation-gateway-url:
post:
tags:
- Create a Connection
summary: Retrieve Authorisation Gateway URL (v2)
description: |
Allow customers to authorise with, and connect to, a provider, using Bud’s __Bud Connect__. Bud Connect is a UI component hosted by Bud that can be integrated into any mobile or web experience, and
allows your customers to connect to and authorise with their chosen provider, allowing Bud to pull their account information using Bud's AISP license.
Using the different configuration options that can be set through the request body you can personalize the experience for your Customer. Please, refer to the documentation below for more information about the available configurations.
Use Bud’s Authorisation Gateway (__Bud Connect__) if you are not regulated as an AISP in order to connect your customers to their banks to share account information. You may still choose to use __Bud Connect__ in order to give the customer a slick account connection experience or to speed up your technical build and integration, even if you are a regulated AISP yourself.
The status of the authorisation step will be provided to you as a path parameter within the `redirect_url` specified within the request payload.
This `redirect_url` is where your customer will be redirected to once they have either failed, or successfully completed, the authorisation process with their provider.
The URL generated with this endpoint is valid for up to 30 minutes. We suggest to generate the URL right before redirecting your Customer to it.
Please note that in order to recieve status updates on a given account connection task, you will need to configure your Callback URL within the developer console.
Once the entire connection process has been completed and the customer's account information is ready to be collected, Bud will send a request to your callback URL.
operationId: v2_ob_authorisation_gateway_url_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthGatewayURLRequestv2'
examples:
All providers:
value:
redirect_url: https://my-agent-webapp.com/connected?my-parameter=xyz
Filter providers list:
value:
redirect_url: https://my-agent-webapp.com/connected?my-parameter=xyz
provider_types:
- retail
Specify provider(s):
value:
redirect_url: https://my-agent-webapp.com/connected?my-parameter=xyz
providers:
- Barclays
- Lloyds
- Natwest
Show the "connect more accounts" button:
value:
redirect_url: https://my-agent-webapp.com/connected?my-parameter=xyz
connect_more_accounts_button: true
Show the account connection summary screen:
value:
redirect_url: https://my-agent-webapp.com/connected?my-parameter=xyz
accounts_summary: true
Show the initial screen as the account summary screen:
value:
redirect_url: https://my-agent-webapp.com/connected?my-parameter=xyz
initial_screen: accounts_summary
Enable an asynchronous connection:
value:
redirect_url: https://my-agent-webapp.com/connected?my-parameter=xyz
enable_async_connect: true
Send consent management email to customer:
value:
redirect_url: https://my-agent-webapp.com/connected?my-parameter=xyz
customer_email: john.doe@email.com
responses:
'201':
description: The resource has been successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthGatewayURLResponse'
example:
operation_id: v2_ob_authorisation_gateway_url_post
data:
url: https://auth.gateway.thisisbud.com/connect?nonce=nu9ysswxk3hnrepo&token=b361e184038e25077cab277ede9362289941da928cd0d9c7ea52107aa2ad0d909d87993a532af47d9794cd5f29ba66128b3dc7f705ce9b044c636c28e31e1bb3ff8e17145a49f42f525bff51945c3a2484c89a05c1b1e484f9b84ee0cfee4640453fd599e71b5111bd880a63cc924fca8c6ce831396e2f4f8b3e5ac994c5c9
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v2_ob_authorisation_gateway_url_post
code_id: failed_validation
message: Failed validation.
errors:
redirect_url: This value should not be blank.
'401':
description: An unauthorised request was received.
'405':
description: The request uses an unexpected HTTP method.
'422':
description: Unprocessable request (e.g. requested providers are in maintenance)
5XX:
description: An unexpected error occurred on the server side.
callbacks:
EventSubscriptionCallBack:
'{$request.body#/redirect_url}':
description: |
This callback is sent to your configured Open Banking Sync Complete webhook URL on the completion of a relevant OB synchronisation task.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Aggregation Sync Notification Callback
deprecated: true
requestBody:
required: true
description: |
This callback is sent to your configured Open Banking Sync Complete webhook URL on the completion of a relevant OB synchronisation task.
__Note__ Deprecated, please use the dedicated `Connect Completed Notification Callback`
content:
application/json:
schema:
$ref: '#/components/schemas/OBSyncWebhookBody'
example:
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Completed
task_type: connect
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
consent_id: f43c4fc9-26f6-4107-a631-4f323f06e5c9
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
ConnectCompletedCallBack:
'{$request.body#/redirect_url}':
description: |
This callback is sent to your configured Open banking connection completed webhook URL on the completion of a connect task.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Connect Completed Notification Callback
requestBody:
required: true
description: This callback is sent to your configured 'Open banking connection completed' webhook URL on the completion of a connect task.
content:
application/json:
schema:
$ref: '#/components/schemas/OBConnectWebhookBody'
examples:
Success:
description: Successful connection
value:
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Completed
result: success
task_type: connect
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
consent_id: f43c4fc9-26f6-4107-a631-4f323f06e5c9
Failure:
description: Failed connect due to a provider failure
value:
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Failed
result: provider_failure
task_type: connect
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
consent_id: f43c4fc9-26f6-4107-a631-4f323f06e5c9
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/v1/open-banking/authorisation-url:
post:
tags:
- Create a Connection
summary: Initiate Provider Authorisation
description: |
Request a new Open Banking authorisation url for a specific Customer and provider. This endpoint should be used when using Bud as a Technical Service Provider(TSP). This means that Bud will be using your license (as a registered Account Information Service Provider (AISP)). This will allow you to use your own interface to connect new account(s).
A generated consent has a 90 day expiry, to allow for re-authentication to extend this expiry the id of the customers previous consent can be included as the `consent_id` property. This re-authenciation if the customer grants consent would extend the consent by another 90 days.
> 📘 Note:
>
> For more information about Consents, please refer to our [guide](https://docs.thisisbud.com/docs/consents).
operationId: open_banking_authorisation_url_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OpenBankingAuthoriseRequest'
examples:
Provider:
value:
provider: Barclays
redirect_url: https://myclientredirecturl.com
responses:
'202':
description: A new Task has been created to obtain the bank's authorisation URL. The generated `task_id` can be used to check the Task's status
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreatedResponseOB'
example:
operation_id: open_banking_authorisation_url_post
data:
task_id: 360e5821-4f18-4077-83f4-c9a7c1768bea
provider: Barclays
metadata:
next_url: /v1/open-banking/authorisation-url/360e5821-4f18-4077-83f4-c9a7c1768bea
next_url_delay: 50
status: Pending
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Parameter missing:
value:
operation_id: open_banking_authorisation_url_post
code_id: failed_validation
message: Failed validation
errors:
customer_id: This value should not be blank
Resource not found:
value:
operation_id: open_banking_authorisation_url_post
code_id: resource_not_found
message: Consent ID could not be found.
errors:
domain_error: Consent ID could not be found.
Provider in Maintenance:
value:
operation_id: open_banking_authorisation_url_post
code_id: provider_maintenance
message: The provider is in maintenance.
errors:
provider: The provider is currently disabled due to planned maintenance or known issues.
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
'405':
description: The request uses an unexpected HTTP method
5XX:
description: An unexpected error occurred on the server side
/v1/open-banking/authorisation-url/{task_id}:
get:
tags:
- Create a Connection
summary: Retrieve Authorisation URL
description: |
Check the status and get the result of an Initiate Provider Authorisation URL task. If the task is not yet completed, the data element will be null.
Once the customer has successfully authorised with the ASPSP, Bud will create a task to fetch the relevant data from the ASPSP. The task id created will be passed back within the supplied re-direct url. Please refer to the Check Connection Status endpoint for updates on this fetching process using the task id provided in the redirect URL.
operationId: open_banking_authorisation_url_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskAuthoriseResponse'
examples:
complete:
summary: Completed
value:
operation_id: open_banking_authorisation_url_get
data:
provider: example_provider
result: success
status: Completed
task_id: 16fa0748-8a6b-455b-9be9-30ae257965d8
url: https://oauth.example.provider.com/authorization.oauth2?
metadata:
next_url: /v1/open-banking/authorisation-url/16fa0748-8a6b-455b-9be9-30ae257965d8
next_url_delay: 50
status: Completed
pending:
summary: Pending
value:
operation_id: open_banking_authorisation_url_get
data:
provider: example_provider
status: Pending
task_id: 16fa0748-8a6b-455b-9be9-30ae257965d8
metadata:
status: Pending
next_url: /v1/open-banking/authorisation-url/16fa0748-8a6b-455b-9be9-30ae257965d8
next_url_delay: 50
failed:
summary: Failed
value:
operation_id: open_banking_authorisation_url_get
data:
provider: example_provider
result: internal_error
status: Failed
task_id: 16fa0748-8a6b-455b-9be9-30ae257965d8
metadata:
status: Failed
next_url: /v1/open-banking/authorisation-url/16fa0748-8a6b-455b-9be9-30ae257965d8
next_url_delay: 50
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: open_banking_authorisation_url_get
code_id: failed_validation
message: Failed validation
errors:
customer_id: This value should not be blank
'404':
description: Task not found
'405':
description: The request uses an unexpected HTTP method
5XX:
description: An unexpected error occurred on the server side
/v1/open-banking/authorisation-codes:
post:
deprecated: true
tags:
- Create a Connection
summary: Submit Authorisation Codes
description: |
When using Bud as a TSP (Technical Service Provider) and doing full app-to-app authorisation, the customer is returned from the provider directly back to your app. Your app will then need to send all the query and hash fragment parameters to Bud so that we can complete the connection.
Query and fragment parameters should be merged with query taking precedence. If you receive a request `/path?a=1#a=2&b=3` then you should perform this request with `{"a":"1","b":"3"}`. Given the nature of the fragment queries most server side languages will not process these so javascript may be required to correctly gather both parameters.
Regardless of what parameters are present, all of them should be sent to Bud so that we can choose to either continue the connection or to map and record the error.
Code and error are shown here only because they are the most common parameters you will see, but this object could contain any number of unspecified properties. Currently state is a common property among all authorisation flows and is the current task ID. The state property is not guaranteed for the future of this API contract and will not be treated as backwards incompatible if a new authentication flow does not use it.
operationId: v1_open_banking_authorisation_codes_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorisationCodesRequest'
examples:
success:
summary: Authorisation has been successful
value:
state: b55f5f00-8e40-4e9e-8c9e-a292a86eb40c
code: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
error:
summary: Authorisation has failed
value:
state: b55f5f00-8e40-4e9e-8c9e-a292a86eb40c
error: access_denied
responses:
'202':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorisationCodesResponse'
examples:
Success:
description: success
value:
operation_id: v1_open_banking_authorisation_codes_post
data:
task_id: b55f5f00-8e40-4e9e-8c9e-a292a86eb40c
provider: Barclays
status: Completed
result: success
Error:
description: error
value:
operation_id: v1_open_banking_authorisation_codes_post
data:
task_id: b55f5f00-8e40-4e9e-8c9e-a292a86eb40c
provider: Barclays
status: Failed
result: auth_denied
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Invalid Body:
description: Invalid Body
value:
operation_id: v1_open_banking_authorisation_codes_post
code_id: failed_body_decode
message: invalid request body
errors:
customer_id: This value should not be blank
Validation Failure:
description: Validation Error
value:
operation_id: v1_open_banking_authorisation_codes_post
code_id: failed_validation
message: invalid request
errors:
state: The field is required
/v2/open-banking/authorisation-codes:
post:
tags:
- Create a Connection
summary: Submit Authorisation Codes V2
description: |
When using Bud as a TSP (Technical Service Provider) and doing full app-to-app authorisation, the customer is returned from the provider directly back to your app. Your app will then need to send all the query and hash fragment parameters to Bud so that we can complete the connection.
Query and fragment parameters should be merged with query taking precedence. If you receive a request `/path?a=1#a=2&b=3` then you should perform this request with `{"a":"1","b":"3"}`. Given the nature of the fragment queries most server side languages will not process these so javascript may be required to correctly gather both parameters.
Regardless of what parameters are present, all of them should be sent to Bud so that we can choose to either continue the connection or to map and record the error.
Code and error are shown here only because they are the most common parameters you will see, but this object could contain any number of unspecified properties. Currently state is a common property among all authorisation flows and is the current task ID. The state property is not guaranteed for the future of this API contract and will not be treated as backwards incompatible if a new authentication flow does not use it.
This endpoint triggers an asynchronous collection of OpenBanking data within the Bud platform. Therefore after calling this endpoint the [Retrieve Connection Status](/reference/open_banking_connect_get) endpoint should be called to retrieve the status of the collection
operationId: v2_open_banking_authorisation_codes_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorisationCodesRequest'
examples:
success:
summary: Authorisation has been successful
value:
state: b55f5f00-8e40-4e9e-8c9e-a292a86eb40c
code: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
error:
summary: Authorisation has failed
value:
state: b55f5f00-8e40-4e9e-8c9e-a292a86eb40c
error: access_denied
responses:
'202':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorisationCodesResponse'
examples:
Success:
description: success
value:
operation_id: v2_open_banking_authorisation_codes_post
data:
task_id: b55f5f00-8e40-4e9e-8c9e-a292a86eb40c
provider: Barclays
status: Completed
result: success
Error:
description: error
value:
operation_id: v2_open_banking_authorisation_codes_post
data:
task_id: b55f5f00-8e40-4e9e-8c9e-a292a86eb40c
provider: Barclays
status: Failed
result: auth_denied
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Invalid Body:
description: Invalid Body
value:
operation_id: v2_open_banking_authorisation_codes_post
code_id: failed_body_decode
message: invalid request body
errors:
customer_id: This value should not be blank
Validation Failure:
description: Validation Error
value:
operation_id: v2_open_banking_authorisation_codes_post
code_id: failed_validation
message: invalid request
errors:
state: The field is required
'409':
description: The code has already been submitted
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Code already submitted:
description: Code already submitted
value:
operation_id: v2_open_banking_authorisation_codes_post
code_id: auth_used
message: auth code has been used before
errors:
code: already used
callbacks:
ConnectCompletedCallBack:
'{$request.body#/redirect_url}':
description: |
This callback is sent to your configured Open banking connection completed webhook URL on the completion of a connect task.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Connect Completed Notification Callback
requestBody:
required: true
description: This callback is sent to your configured 'Open banking connection completed' webhook URL on the completion of a connect task.
content:
application/json:
schema:
$ref: '#/components/schemas/OBConnectWebhookBody'
examples:
Success:
description: Successful connection
value:
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Completed
result: success
task_type: connect
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
consent_id: f43c4fc9-26f6-4107-a631-4f323f06e5c9
Failure:
description: Failed connect due to a provider failure
value:
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Failed
result: provider_failure
task_type: connect
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
consent_id: f43c4fc9-26f6-4107-a631-4f323f06e5c9
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/v1/open-banking/connect/{connection_task_id}:
get:
tags:
- Create a Connection
summary: Retrieve Connection Status
description: |
Check the status of an account connection task. If the task is not yet completed, the status will be shown as pending. If the status is completed, then the data is ready to be ingested.
The __connection_task_id__ is provided as a parameter in the redirect url after the Customer has undergone a successful authorisation with a relevant Open Banking provider.
operationId: open_banking_connect_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/ConnectionTaskId'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/OpenBankingConnectResponse'
examples:
completed:
summary: Completed
value:
operation_id: open_banking_connect_get
data:
bank_name: Barclays
provider: Barclays
reconnect_required: false
result: success
status: Completed
step: 4
task_id: 030c85d8-bbbe-4ef9-894e-7e56a2e02437
text: Completed
metadata:
status: Completed
next_url: /v1/open-banking/connect/360e5821-4f18-4077-83f4-c9a7c1768bea
next_url_delay: 50
pending:
summary: Pending
value:
operation_id: open_banking_connect_get
data:
bank_name: Barclays
provider: Barclays
reconnect_required: false
status: Pending
step: 2
task_id: 030c85d8-bbbe-4ef9-894e-7e56a2e02437
text: Fetching accounts
metadata:
status: Pending
next_url: /v1/open-banking/connect/360e5821-4f18-4077-83f4-c9a7c1768bea
next_url_delay: 50
failed:
summary: Failed
value:
operation_id: open_banking_connect_get
data:
bank_name: Barclays
provider: Barclays
reconnect_required: false
result: auth_denied
status: Failed
step: 3
task_id: 030c85d8-bbbe-4ef9-894e-7e56a2e02437
text: Fetching balances and transactions
metadata:
status: Failed
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: open_banking_connect_get
code_id: failed_validation
message: Failed validation
errors:
customer_id: This value should not be blank
'404':
description: Task not found
'405':
description: The request uses an unexpected HTTP method
5XX:
description: An unexpected error occurred on the server side
/v1/open-banking/refresh:
post:
deprecated: true
tags:
- Manage a Connection
summary: Initiate Refresh
description: |
Instruct Bud to retrieve the latest account information for a customer. Refresh the accounts from a single provider with an existing connection.
By default this task will retrieve transactions since the last pull of transactions less seven days. This can be overridden using the `from` body parameter to a maximum of 90 days previously.
After initiating this long running process, make sure to check the status of the it till completion before trying to access the Customer's data or initiating another refresh.
If the customer's provider was fetched (connect or refresh) within the last hour, the endpoint will return the task_id of the previous task instead of refreshing the data again.
If the customer's consent has been revoked or expired for this provider, Bud will be unable to refresh the account.
This will be confirmed in the response of the refresh status endpoint associated with the `task_id` provided in the response to this endpoint, where the `reconnect_required` field will set to `true` and status set to `Completed`.
operationId: open_banking_refresh_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- in: header
name: X-Customer-Ip-Address
schema:
type: string
required: false
description: |
The IP address of the personal device the customer is initiating the refresh from.
This header should _only_ be supplied if the customer has initiated the refresh from a personal device, and never if the refresh has been initated from an automated process such as a script.
The IP address is forwarded to the provider and can help avoid hitting limits on how frequently a refresh can be initiated.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OpenBankingRefreshRequest'
example:
provider: Barclays
from: '2019-03-01T00:00:00+00:00'
to: '2019-06-01T00:00:00+00:00'
responses:
'202':
description: A new Task has been generated to request the Customer's bank account refresh. The generated `task_id` can be used to check the Task's status.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreatedResponseOB'
example:
operation_id: open_banking_refresh_post
data:
provider: Barclays
task_id: 360e5821-4f18-4077-83f4-c9a7c1768bea
metadata:
next_url: /v1/open-banking/refresh/360e5821-4f18-4077-83f4-c9a7c1768bea
next_url_delay: 50
status: Pending
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Parameter missing:
value:
operation_id: open_banking_refresh_post
code_id: failed_validation
message: Failed validation
errors:
customer_id: This value should not be blank
customer_secret: This value should not be blank
Provider in Maintenance:
value:
operation_id: open_banking_refresh_post
code_id: provider_maintenance
message: The provider is in maintenance.
errors:
provider: The provider is currently disabled due to planned maintenance or known issues.
'405':
description: The request uses an unexpected HTTP method
5XX:
description: An unexpected error occurred on the server side
callbacks:
EventSubscriptionCallBack:
'{$request.body#/redirect_url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Aggregation Sync Notification Callback
deprecated: true
requestBody:
required: true
description: |
This callback is sent to your configured Open Banking Sync Complete webhook URL on the completion of a relevant OB synchronisation task.
__Note__ Deprecated, please use the dedicated `Refresh Completed Notification Callback`
content:
application/json:
schema:
$ref: '#/components/schemas/OBSyncWebhookBody'
example:
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Completed
task_type: refresh
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
consent_id: f43c4fc9-26f6-4107-a631-4f323f06e5c9
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
RefreshCompletedCallBack:
'{$request.body#/redirect_url}':
description: |
This callback is sent to your configured 'Open banking refresh completed' webhook URL on the completion of a connect task.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Refresh Completed Notification Callback
requestBody:
required: true
description: This callback is sent to your configured 'Open banking refresh completed' webhook URL on the completion of a refresh task.
content:
application/json:
schema:
$ref: '#/components/schemas/OBRefreshWebhookBody'
examples:
Success:
description: Successful refresh
value:
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Completed
result: success
task_type: refresh
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
reconnect_required: 'false'
has_new_transactions: 'true'
consent_id: f43c4fc9-26f6-4107-a631-4f323f06e5c9
Failure:
description: Failed refresh due to a consent being revoked
value:
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Failed
result: connection_revoked
task_type: refresh
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
reconnect_required: 'true'
has_new_transactions: 'false'
consent_id: f43c4fc9-26f6-4107-a631-4f323f06e5c9
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/v1/open-banking/refresh/{task_id}:
get:
deprecated: true
tags:
- Manage a Connection
summary: Retrieve Refresh Status
description: |
Check the status of an account information refresh task. If the task is not yet completed, the status will be shown as pending.
If the status is completed, then the data is ready to be collected via the [Retrieve Financial Data](/reference/retrieve-financial-data) endpoints.
Successful requests will include `step` (1-4) and associated `text` values to indicate the current progress of the refresh task.
Make sure to check the status of the task till completion before trying to access the Customer's data or initiating another process.
When the task is successful, we include in the response body a `metadata.has_new_transactions` boolean attribute that tells you if the refresh resulted in storing new data. This attribute must be used to
decide if it's necessary to pull the Customer's data or not.
When the refresh fails, we include the reason of the failure as part of the `data.result` attribute. We also include the `data.reconnect_required` boolean attribute that indicates if the consent used to
fetch the data for this customer and provider is no longer valid. If reconnect_required is true, the customer will need to go through the bank account connection flow again.
operationId: open_banking_refresh_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/OpenBankingRefreshResponse'
examples:
completed:
summary: Completed
value:
operation_id: open_banking_refresh_get
data:
provider: Barclays
status: Completed
result: success
reconnect_required: false
step: 4
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
text: Completed
metadata:
has_new_transactions: true
status: Completed
pending:
summary: Pending
value:
operation_id: open_banking_refresh_get
data:
provider: Barclays
status: Pending
reconnect_required: false
step: 1
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
text: Fetching access token
metadata:
status: Pending
next_url: /v1/open-banking/refresh/360e5821-4f18-4077-83f4-c9a7c1768bea
next_url_delay: 50
failed_provider_failure:
summary: Provider Failure
value:
operation_id: open_banking_refresh_get
data:
task_id: 1ceb1d81-a80e-4825-a7c0-4d69424c9874
provider: Barclays
status: Failed
result: provider_failure
reconnect_required: false
step: 2
text: Fetching accounts
metadata:
status: Failed
failed_connection_not_found:
summary: Connection not found
value:
operation_id: open_banking_refresh_get
data:
task_id: 1ceb1d81-a80e-4825-a7c0-4d69424c9874
provider: Barclays
status: Failed
result: connection_not_found
reconnect_required: false
step: 4
text: Completed
metadata:
status: Failed
failed_reconnect_required:
summary: Reconnection Required
value:
operation_id: open_banking_refresh_get
data:
provider: Barclays
status: Failed
result: connection_revoked
reconnect_required: true
step: 4
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
text: Completed
metadata:
status: Failed
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: open_banking_refresh_get
code_id: failed_validation
message: Failed validation
errors:
customer_id: This value should not be blank
'405':
description: The request uses an unexpected HTTP method
5XX:
description: An unexpected error occurred on the server side
/open-banking/v2/refresh:
post:
tags:
- Manage a Connection
summary: Initiate Refresh V2
description: |
Instruct Bud to retrieve the latest account information for a customer. Refresh the accounts from all providers with an existing connection.
By default this task will retrieve transactions since the last pull of transactions less seven days. This can be overridden using the `from` body parameter to a maximum of 90 days previously.
On completion of this task Bud will send a webhook to your configured endpoint including details of the refresh completed and the status of the refresh for each provider. Alternatively the status of the task can be checked using the Retrieve Refresh Status V2 endpoint. Please check that the task has completed successfully before trying to access the Customer's data or initiating another refresh.
If a similar refresh (same providers) for this customer has been initiated within the last hour, the endpoint will return the task_id of the previous task instead of refreshing the data again.
If the customer's consent has been revoked or expired for a provider, Bud will be unable to refresh the customers account at that provider.
This will be confirmed in the response of the refresh status endpoint associated with the `task_id` provided in the response to this endpoint, where the `reconnect_required` field will set to `true` and status set to `Completed`. If the consent within the Bud system was marked as `Authorised` at this point the consent will be updated to `Revoked`
To simplify your integration Bud is able to take control of your background refreshes and manage these regularly for you. Full details can be found on the following [guide](https://docs.thisisbud.com/docs/open-banking-hosted-refreshes)
operationId: v2_open_banking_refresh_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- in: header
name: X-Customer-Ip-Address
schema:
type: string
required: false
description: |
The IP address of the personal device the customer is initiating the refresh from.
This header should _only_ be supplied if the customer has initiated the refresh from a personal device, and never if the refresh has been initated from an automated process such as a script.
The IP address is forwarded to the provider and can help avoid hitting limits on how frequently a refresh can be initiated.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OpenBankingRefreshRequestV2'
example:
from: '2019-03-01T00:00:00+00:00'
to: '2019-06-01T00:00:00+00:00'
responses:
'202':
description: A new Task has been generated to request the Customer's bank account refresh. The generated `task_id` can be used to check the Task's status.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreatedV2ResponseOB'
example:
operation_id: v2_open_banking_refresh_post
data:
task_id: 360e5821-4f18-4077-83f4-c9a7c1768bea
sub_tasks:
- provider: Natwest_Sandbox
task_id: 030d244b-c2d8-4698-b919-69a6c6974c75
- provider: Bank_Of_Bud
task_id: 030d7563-eb58-4319-9a62-f008ce48bd6c
metadata:
next_url: /v2/open-banking/refresh/360e5821-4f18-4077-83f4-c9a7c1768bea
next_url_delay: 500
status: Pending
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Parameter missing:
value:
operation_id: v2_open_banking_refresh_post
code_id: failed_validation
message: Failed validation
errors:
customer_id: This value should not be blank
'405':
description: The request uses an unexpected HTTP method
5XX:
description: An unexpected error occurred on the server side
callbacks:
RefreshV2CompletedCallBack:
'{$request.body#/redirect_url}':
description: |
This callback is sent to your configured 'Open banking refresh v2 completed' webhook URL on the completion of a refresh v2 task. This includes details of refreshes completed for all providers
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Refresh Completed Notification Callback
requestBody:
required: true
description: This callback is sent to your configured 'Open banking refresh completed V2' webhook URL on the completion of a refresh task. This includes details of refreshes completed for all providers.
content:
application/json:
schema:
$ref: '#/components/schemas/OBV2WebhookBody'
examples:
Success:
description: Successful refresh
value:
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
event: open_banking.v2.refresh.completed
has_new_transactions: true
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
result: success
status: Completed
sub_tasks:
- task_id: 03af1639-78a6-402d-809b-902a0b00a789
has_new_transactions: true
provider: Bank_Of_Bud
reconnect_required: false
result: success
status: Completed
consent_ids:
- 2c7b5faf-2d11-47b1-b9e6-ce95f195259b
account_ids:
- d8b1390e-0106-4b65-8298-d6a4f13e662c
Failure:
description: Failed refresh due to a consent being revoked
value:
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
event: open_banking.v2.refresh.completed
has_new_transactions: false
task_id: 03af1639-78a6-402d-809b-902a0b001234
status: Failed
result: connection_revoked
sub_tasks:
- task_id: 03af1639-78a6-402d-809b-902a0b00b283
has_new_transactions: false
provider: Bank_Of_Bud
reconnect_required: true
result: connection_revoked
status: Failed
consent_ids:
- 2c7b5faf-2d11-47b1-b9e6-ce95f195259b
account_ids:
- d8b1390e-0106-4b65-8298-d6a4f13e662c
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
ProviderRefreshCompletedCallBack:
'{$request.body#/redirect_url}':
description: |
This callback is sent to your configured 'Open banking refresh v2 provider completed' webhook URL on the completion of a refresh task. This webhook includes details of the refresh completed for a specific provider.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Provider Refresh Completed Notification Callback
requestBody:
required: true
description: This callback is sent to your configured 'Open banking refresh v2 provider completed' webhook URL when the refresh completes for each provider in a refresh v2 task.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderOBV2WebhookBody'
examples:
Success:
description: Successful refresh
value:
event: open_banking.v2.refresh.provider.completed
task_id: 03af1639-78a6-402d-809b-902a0b00a789
has_new_transactions: true
provider: Bank_Of_Bud
reconnect_required: false
result: success
status: Completed
consent_ids:
- 2c7b5faf-2d11-47b1-b9e6-ce95f195259b
account_ids:
- d8b1390e-0106-4b65-8298-d6a4f13e662c
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
Failure:
description: Failed refresh due to a consent being revoked
value:
event: open_banking.v2.refresh.provider.completed
task_id: 03af1639-78a6-402d-809b-902a0b00a789
has_new_transactions: false
provider: Bank_Of_Bud
reconnect_required: true
result: connection_revoked
status: Failed
consent_ids:
- 2c7b5faf-2d11-47b1-b9e6-ce95f195259b
account_ids:
- d8b1390e-0106-4b65-8298-d6a4f13e662c
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/open-banking/v2/refresh/{task_id}:
get:
tags:
- Manage a Connection
summary: Retrieve Refresh Status V2
description: |
Check the status of an account information refresh task. If the task is not yet completed, the status will be shown as pending.
If the status is completed, then the data is ready to be collected via the [Retrieve Financial Data](/reference/retrieve-financial-data) endpoints.
To monitor the status of a refresh task we provide two methods. The preferred approach is to utilise the webhook functionality within the Bud platform where Bud will send a webhook to your configured endpoint when the task completes. Alternatively you can poll this endpoint to retrieve the status of the task.
Please ensure that you either receive a webhook with a status of `Completed` and result of `success` or this endpoint returns a status of `Completed` and result of `success` before trying to access the Customer's data or initiating another process.
When the task is successful, we include in the response body a `metadata.has_new_transactions` boolean attribute that tells you if the refresh resulted in storing new data. This attribute must be used to
decide if it's necessary to pull the Customer's data or not.
When the refresh fails, we include the reason of the failure as part of the `data.result` attribute. We also include the `data.sub_tasks[i].reconnect_required` boolean attribute that indicates if the consent used to
fetch the data for this customer and provider is no longer valid. If reconnect_required is true, the customer will need to go through the bank account connection flow and the consent will be marked as revoked.
When only a subset of sub tasks fails the main task will be marked as `Failed` but for each provider where the refresh was successful (result is equal to `success`) customers data will be updated and available from the [Retrieve Financial Data](/reference/retrieve-financial-data) endpoints.
In the case of a partial success you are able to specify the `providers` body parameter to the [Initiate Refresh V2](/reference/v2_open_banking_refresh_post) endpoint to initiate a refresh for the failing provider(s).
operationId: v2_open_banking_refresh_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/OpenBankingRefreshV2Response'
examples:
completed:
summary: Completed
value:
operation_id: v2_open_banking_refresh_get
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Completed
result: success
has_new_transactions: true
sub_tasks:
- task_id: 030d244b-c2d8-4698-b919-69a6c6974c75
provider: Natwest_Sandbox
status: Completed
result: success
reconnect_required: false
has_new_transactions: true
- task_id: 030d7563-eb58-4319-9a62-f008ce48bd6c
provider: Bank_Of_Bud
status: Completed
result: success
reconnect_required: false
has_new_transactions: false
metadata:
status: Completed
pending:
summary: Pending
value:
operation_id: v2_open_banking_refresh_get
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Pending
sub_tasks:
- task_id: 030d244b-c2d8-4698-b919-69a6c6974c75
provider: Natwest_Sandbox
status: Pending
- task_id: 030d7563-eb58-4319-9a62-f008ce48bd6c
provider: Bank_Of_Bud
status: Pending
metadata:
status: Pending
next_url: /v2/open-banking/refresh/03af1639-78a6-402d-809b-902a0b00a77d
next_url_delay: 500
partially_complete:
summary: Partially Complete
value:
operation_id: v2_open_banking_refresh_get
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Pending
sub_tasks:
- task_id: 030d244b-c2d8-4698-b919-69a6c6974c75
provider: Natwest_Sandbox
status: Pending
- task_id: 030d7563-eb58-4319-9a62-f008ce48bd6c
provider: Bank_Of_Bud
status: Completed
result: success
reconnect_required: false
has_new_transactions: false
metadata:
status: Pending
next_url: /v2/open-banking/refresh/03af1639-78a6-402d-809b-902a0b00a77d
next_url_delay: 500
failed_provider_failure:
summary: Provider Failure
value:
operation_id: v2_open_banking_refresh_get
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Failed
sub_tasks:
- task_id: 030d244b-c2d8-4698-b919-69a6c6974c75
provider: Natwest_Sandbox
status: Failed
result: provider_failure
reconnect_required: false
- task_id: 030d7563-eb58-4319-9a62-f008ce48bd6c
provider: Bank_Of_Bud
status: Completed
result: success
reconnect_required: false
has_new_transactions: false
metadata:
status: Failed
failed_connection_not_found:
summary: Connection not found
value:
operation_id: v2_open_banking_refresh_get
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Failed
sub_tasks:
- task_id: 030d244b-c2d8-4698-b919-69a6c6974c75
provider: Natwest_Sandbox
status: Failed
result: connection_not_found
reconnect_required: true
- task_id: 030d7563-eb58-4319-9a62-f008ce48bd6c
provider: Bank_Of_Bud
status: Failed
result: connection_not_found
reconnect_required: true
metadata:
status: Failed
failed_provider_in_maintenance:
summary: Provider In Maintenance
value:
operation_id: v2_open_banking_refresh_get
data:
task_id: 03af1639-78a6-402d-809b-902a0b00a77d
status: Failed
sub_tasks:
- task_id: 030d244b-c2d8-4698-b919-69a6c6974c75
provider: Natwest_Sandbox
status: Failed
result: provider_maintenance
reconnect_required: false
- task_id: 030d7563-eb58-4319-9a62-f008ce48bd6c
provider: Bank_Of_Bud
status: Failed
result: provider_maintenance
reconnect_required: false
metadata:
status: Failed
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v2_open_banking_refresh_get
code_id: failed_validation
message: Failed validation
errors:
customer_id: This value should not be blank
'405':
description: The request uses an unexpected HTTP method
5XX:
description: An unexpected error occurred on the server side
/v1/open-banking/account-access-consents:
get:
tags:
- Manage a Connection
summary: Retrieve Customer Consents
description: |
Retrieve the list of all available Open Banking consents granted by the customer.
> 📘 Note:
>
> For more information about Consents, please refer to our [guide](https://docs.thisisbud.com/docs/consents).
operationId: open_banking_connections_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/ConsentStatus'
responses:
'200':
description: The list of consents
content:
application/json:
schema:
$ref: '#/components/schemas/GetOBConsentsResponse'
examples:
withSecret:
summary: Request With Secret
description: A retrive consents request including the customer secret
value:
operation_id: open_banking_connections_get
data:
- id: 1ceb1d81-a80e-4825-a7c0-4d69424c9874
customer_id: 8e826e72-5cab-4426-897f-5317992a95f0
provider: Natwest_Sandbox
transaction_from_date: '2020-03-23T14:46:32Z'
expiration_date: '2021-06-21T14:46:33Z'
created_at: '2021-03-23T14:46:33Z'
last_consented_on: '2021-03-23T14:47:01Z'
status: authorised
resources:
- accounts
- balances
- transactions
permissions:
- ReadAccounts
- ReadBalances
- ReadTransactions
raw_version: v1.1
raw_format: obie
raw:
ConsentId: 87ccf4c3-62b1-49c1-9a49-26919f954deb
TransactionFromDateTime: null
StatusUpdateDateTime: null
Status: AwaitingAuthorisation
Permissions:
- ReadAccountsDetail
- ReadBalances
- ReadTransactionsDetail
- ReadTransactionsDebits
- ReadTransactionsCredits
account_ids:
- aa86f72c-476a-3355-b54c-614a815fae40
last_synced_at: '2021-06-15T11:01:30.07Z'
- id: a080272e-c449-4a75-861a-9feb53075946
customer_id: 8e826e72-5cab-4426-897f-5317992a95f0
provider: Amex
transaction_from_date: '2020-04-24T15:46:32Z'
transaction_to_date: '0001-01-01T00:00:00Z'
expiration_date: '2021-07-21T14:46:33Z'
created_at: '2021-04-24T15:42:13Z'
last_consented_on: '2021-04-24T15:42:13Z'
status: authorised
resources:
- accounts
- balances
- transactions
permissions:
- ReadAccounts
- ReadBalances
- ReadTransactions
raw_version: v1.1
raw_format: amex
raw: null
account_ids:
- bb98k51y-564t-8560-c99d-232b977gef68
last_synced_at: '2021-06-16T09:13:41.32Z'
metadata:
results: 2
withoutSecret:
summary: Request Without Secret
description: A retrieve consents request without the customer secret
value:
operation_id: open_banking_connections_get
data:
- id: 1ceb1d81-a80e-4825-a7c0-4d69424c9874
customer_id: 8e826e72-5cab-4426-897f-5317992a95f0
provider: Natwest_Sandbox
transaction_from_date: '2020-03-23T14:46:32Z'
expiration_date: '2021-06-21T14:46:33Z'
created_at: '2021-03-23T14:46:33Z'
last_consented_on: '2021-03-23T14:47:01Z'
status: authorised
resources:
- accounts
- balances
- transactions
permissions:
- ReadAccounts
- ReadBalances
- ReadTransactions
raw_version: v1.1
raw_format: obie
raw:
ConsentId: 87ccf4c3-62b1-49c1-9a49-26919f954deb
TransactionFromDateTime: null
StatusUpdateDateTime: null
Status: AwaitingAuthorisation
Permissions:
- ReadAccountsDetail
- ReadBalances
- ReadTransactionsDetail
- ReadTransactionsDebits
- ReadTransactionsCredits
last_synced_at: '2021-06-15T11:01:30.07Z'
- id: a080272e-c449-4a75-861a-9feb53075946
customer_id: 8e826e72-5cab-4426-897f-5317992a95f0
provider: Amex
transaction_from_date: '2020-04-24T15:46:32Z'
transaction_to_date: '0001-01-01T00:00:00Z'
expiration_date: '2021-07-21T14:46:33Z'
created_at: '2021-04-24T15:42:13Z'
last_consented_on: '2021-04-24T15:42:13Z'
status: authorised
resources:
- accounts
- balances
- transactions
permissions:
- ReadAccounts
- ReadBalances
- ReadTransactions
raw_version: v1.1
raw_format: amex
raw: null
last_synced_at: '2021-06-16T09:13:41.32Z'
metadata:
results: 2
'400':
description: Bad Request that fails validations on headers
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
5XX:
description: An unexpected error occurred on the server side
/v1/open-banking/account-access-consent/revoke:
post:
tags:
- Manage a Connection
summary: Initiate Revoke Consent
description: |
Start a task to remove consent and remove Bud’s ability to download further information for a specified customer account.
This will revoke `all` the consents for the specified provider associated to the customer.
To check the status of this task, use the `Retrieve Revoke Consent Status` using the returned `task_id`.
Alternatively, there is a `Open Banking Consent Revoked` webhook that will trigger per consent successfully revoked. As such this task could generate multiple of these.
operationId: open_banking_account_access_consent_revoke_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeAccountAccessIntentRequest'
example:
provider: Barclays
responses:
'202':
description: The request has been accepted for processing
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeTaskCreatedResponse'
example:
operation_id: open_banking_revoke_post
data:
provider: Monzo
task_id: 1ceb1d81-a80e-4825-a7c0-4d69424c9874
metadata:
status: Pending
next_url: /v1/open-banking/account-access-consent/revoke/1ceb1d81-a80e-4825-a7c0-4d69424c9874
next_url_delay: 50
'400':
description: Bad Request that fails validations on headers & payload
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
5XX:
description: An unexpected error occurred on the server side
callbacks:
ConsentRevokedCallBack:
'{$request.body#/redirect_url}':
description: |
This callback is sent to your configured Open Banking Consent Revoked webhook URL when a consent is moved to a revoked status
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Consent Revoked Notification Callback
requestBody:
required: true
description: This callback is sent to your configured `Open Banking Consent Revoked` webhook URL when a consent has moved to a revoked status
content:
application/json:
schema:
$ref: '#/components/schemas/OBConsentWebhookBody'
example:
data:
event: open_banking.consent.revoked
consent_id: 03af1639-78a6-402d-809b-902a0b00a77d
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
provider: Monzo
updated_at: '2023-10-02T14:05:55Z'
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/v1/open-banking/account-access-consent/revoke/{task_id}:
get:
tags:
- Manage a Connection
summary: Retrieve Revoke Consent Status
description: |
Check the status and result of a Revoke Consent task.
Use the `task_id` taken from a successful `Initiate Revoke Consent` request.
operationId: open_banking_account_access_consent_revoke_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeAccountAccessIntentTastStatusResponse'
examples:
completed:
summary: Completed
value:
operation_id: open_banking_revoke_task_get
data:
task_id: 1ceb1d81-a80e-4825-a7c0-4d69424c9874
provider: Natwest
status: Completed
result: success
metadata:
status: Completed
pending:
summary: Pending
value:
operation_id: open_banking_revoke_task_get
data:
task_id: 1ceb1d81-a80e-4825-a7c0-4d69424c9874
provider: Natwest
status: Pending
metadata:
status: Pending
next_url: /v1/open-banking/account-access-consent/revoke/1ceb1d81-a80e-4825-a7c0-4d69424c9874
next_url_delay: 50
failed:
summary: Failed
value:
operation_id: open_banking_revoke_task_get
data:
task_id: 1ceb1d81-a80e-4825-a7c0-4d69424c9874
provider: Natwest
status: Failed
metadata:
status: Failed
'400':
description: Bad Request that fails validations on headers & payload
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeAccountAccessIntentTaskStatusValidationError'
examples:
missing_customer_header:
summary: Missing X-Customer-Id header
value:
operation_id: open_banking_revoke_task_get
code_id: failed_validation
message: invalid request
errors:
customer-id: This value should not be blank
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
5XX:
description: An unexpected error occurred on the server side
/v1/open-banking/account-access-consents/{consent_id}/reconfirm:
post:
tags:
- Manage a Connection
summary: Reconfirm Consent
description: |
Reconfirm a customer's consent to extend the expiration date by 90 days. If the provider requires SCA authentication or the consent status is not showing "Authorised" or the consent is expired, the `reconnect_required` flag will show as true.
If true, you should make a call to the Retrieve Authoirsation Gateway URL endpoint with the `reconfirm_consent` flag set to true to direct your customer to the reconfirm consent journey.
If false, the consent has been extended.
> 📘 Note:
>
> This endpoint should only be used by TSP clients (Technical Service Provider).
>
> Requests to this endpoint from TPP clients (Third Party Provider) will fail, i.e. you are not yourself regulated as an PISP (Payment Initiation Service Provider).
>
>
> For more information about Consents, please refer to our [guide](https://docs.thisisbud.com/docs/consents).
operationId: open_banking_consents_reconfirm_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/CustomerIPAddress'
- $ref: '#/components/parameters/ConsentId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReconfirmConsentResponse'
examples:
no_reconnect:
summary: Reconnect not required
value:
operation_id: open_banking_consents_reconfirm_post
data:
provider_id: Barclays
reconnect_required: false
reconnect:
summary: Reconnect required
value:
operation_id: open_banking_consents_reconfirm_post
data:
provider_id: Barclays
reconnect_required: true
'400':
description: Bad Request that fails validations on headers & payload
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
'404':
description: Consent not found
5XX:
description: An unexpected error occurred on the server side
callbacks:
ConsentReconfirmedCallBack:
'{$request.body#/redirect_url}':
description: |
This callback is sent to your configured Open Banking Consent Reconfirmed webhook URL when a consent is successfully reconfirmed
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Consent Reconfirmed Notification Callback
requestBody:
required: true
description: This callback is sent to your configured `Open Banking Consent Reconfirmed` webhook URL when a consent has been successfully reconfirmed
content:
application/json:
schema:
$ref: '#/components/schemas/OBConsentWebhookBody'
example:
data:
event: open_banking.consent.reconfirmed
consent_id: 03af1639-78a6-402d-809b-902a0b00a77d
customer_id: b6f898f8-99e8-4529-8e90-64d96fe05aa4
provider: Monzo
updated_at: '2023-10-02T14:05:55Z'
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/v2/ingest/accounts:
post:
tags:
- Ingest First Party Data
summary: Ingest Accounts
description: |
This endpoint is for pushing customer(s) account(s) and balance(s) through the Bud architecture.
It can ingest data for multiple customers per request.
By default, this is synchronous and will report any issue with the data in the response.
If a 'X-Disable-Synchronous' header is present and set to true, the process will create a task in the background and be entirely 'non-blocking'.
In this scenario, the response metadata will contain a Task ID and the next URL which would then be used for finding out the operation's result.
operationId: v2_ingest_accounts_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/IngestAccountsContentType'
- name: X-Disable-Synchronous
in: header
description: |
If present and set to true, a task is created and a response is returned immediately.
Note: This flag cannot be set to `true` if a `customer_idempotent_identifier` is supplied instead of a `customer_id`.
schema:
type: boolean
default: false
requestBody:
required: true
content:
application/bud-accounts+json:
schema:
$ref: '#/components/schemas/IngestAccountsRequest'
examples:
ingest_request_with_customer_id:
summary: Ingest Accounts Request (With Customer ID)
value:
- customer_id: c3339af9-2426-44d4-9c4d-ddb8fd281e23
accounts:
- provider: Barclays
account_id: 99473c28-21cf-4a9a-b79e-fd643dd7a4bc
currency: GBP
account_type: Personal
account_sub_type: CurrentAccount
account_identifiers:
- type: uk_account_number
value: '32165444'
- type: uk_sort_code
value: '987654'
balances:
- amount:
value: '7.00'
currency: GBP
credit_debit_indicator: outgoing_debit
credit_line:
- included: true
amount:
value: '200.00'
currency: GBP
type: Credit
date_time: '2020-12-01T00:00:00Z'
type: InterimBooked
- customer_id: 85db4cdf-5f79-4f4e-8388-f9a52da598a2
accounts:
- provider: Lloyds
account_id: bfd4ea71-58d7-4b24-8820-95029875cc9a
currency: GBP
account_type: Personal
account_sub_type: CurrentAccount
account_identifiers:
- type: uk_account_number
value: '12312300'
- type: uk_sort_code
value: '123123'
balances:
- amount:
value: '70005.00'
currency: GBP
credit_debit_indicator: incoming_credit
credit_line:
- included: true
amount:
value: '100.00'
currency: GBP
type: Credit
date_time: '2020-12-01T00:00:00Z'
type: InterimBooked
ingest_request_with_customer_idempotent_identifier:
summary: Ingest Accounts Request (With Customer Idempotent Identifier)
value:
- customer_idempotent_identifier: your_internal_id
accounts:
- provider: Barclays
account_id: 99473c28-21cf-4a9a-b79e-fd643dd7a4bc
currency: GBP
account_type: Personal
account_sub_type: CurrentAccount
account_identifiers:
- type: uk_account_number
value: '32165444'
- type: uk_sort_code
value: '987654'
balances:
- amount:
value: '7.00'
currency: GBP
credit_debit_indicator: outgoing_debit
credit_line:
- included: true
amount:
value: '200.00'
currency: GBP
type: Credit
date_time: '2020-12-01T00:00:00Z'
type: InterimBooked
- customer_idempotent_identifier: your_internal_id
accounts:
- provider: Lloyds
account_id: bfd4ea71-58d7-4b24-8820-95029875cc9a
currency: GBP
account_type: Personal
account_sub_type: CurrentAccount
account_identifiers:
- type: uk_account_number
value: '12312300'
- type: uk_sort_code
value: '123123'
balances:
- amount:
value: '70005.00'
currency: GBP
credit_debit_indicator: incoming_credit
credit_line:
- included: true
amount:
value: '100.00'
currency: GBP
type: Credit
date_time: '2020-12-01T00:00:00Z'
type: InterimBooked
responses:
'202':
description: A new Task has been created to ingest the given accounts. The generated `task_id` can be used to check the Task's status
content:
application/json:
schema:
$ref: '#/components/schemas/IngestV2AsyncResponse'
example:
operation_id: v2_ingest_accounts_post
metadata:
task_id: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url: /v2/ingest/status/4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url_delay: 500
'204':
description: The data has been ingested successfully. Response has no body
'400':
description: Bad Request that fails validations on headers and/or payload
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BodyDecodeError'
- $ref: '#/components/schemas/FirstPartyIngestionGenericError'
- $ref: '#/components/schemas/AccountsDataValidationError'
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
5XX:
description: An unexpected error occurred on the server side
callbacks:
FPIIngestSucceededCallback:
'{$request.body#/redirect_url}':
description: |
Should the ingestion task succeed, this callback is sent to your configured 'First Party Data Ingestion Events' webhook URL on the completion of a Ingest Accounts task.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: First Party Ingestion Succeeded Callback
requestBody:
required: true
description: Should the ingestion task succeed, this callback is sent to your configured 'First Party Data Ingestion Events' webhook URL on the completion of a Ingest Accounts task.
content:
application/json:
schema:
$ref: '#/components/schemas/FPIIngestSucceededWebhookBody'
examples:
Success:
description: Successful ingestion
value:
data:
event: first_party_ingester.ingest.succeeded
operation_id: v2_ingest_accounts_post
task_id: 6d37e192-1fdb-407d-82c6-58ee38cb60db
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
FPIIngestFailedCallback:
'{$request.body#/redirect_url}':
description: |
Should the ingestion task fail, this callback is sent to your configured 'First Party Data Ingestion Events' webhook URL on the completion of a Ingest Accounts task.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: First Party Ingestion Failed Callback
requestBody:
required: true
description: Should the ingestion task fail, this callback is sent to your configured 'First Party Data Ingestion Events' webhook URL on the completion of a Ingest Accounts task.
content:
application/json:
schema:
$ref: '#/components/schemas/FPIIngestFailedWebhookBody'
examples:
Success:
description: First Party Ingestion Failed
value:
data:
event: first_party_ingester.ingest.failed
operation_id: v2_ingest_transactions_post
task_id: 6d37e192-1fdb-407d-82c6-58ee38cb60db
result: data_mapping_error
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/ingestion/v3/accounts/close:
post:
tags:
- Ingest First Party Data
summary: Close Accounts
description: |
Close one or more accounts for a given customer. This will set the account status to closed and set the `closed_at` field on the __Retrieve Accounts V3__ response.
If an account is already closed, then the request will be ignored, and the `closed_at` field will remain unchanged.
If a 400 response is returned, any accountIDs or customerIDs __not__ defailted in the error response will have been closed succesfully.
operationId: v3_ingest_accounts_close_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CloseAccountsRequest'
examples:
With Customer Idempotent Identifier:
value:
- customer_idempotent_identifier: your_internal_id
account_ids:
- 275fbbfe-209c-4329-a38b-b324aa386c56
metadata:
as_of: '2025-09-22T14:55:09.254Z'
With Customer ID:
value:
- customer_id: c3339af9-2426-44d4-9c4d-ddb8fd281e23
account_ids:
- 275fbbfe-209c-4329-a38b-b324aa386c56
metadata:
as_of: '2025-09-22T14:55:09.254Z'
responses:
'204':
description: All accounts have been closed successfully. Response has no body.
'400':
description: Bad Request that fails validations on headers and/or payload
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorWihoutErrRequired'
examples:
account_not_found_customer_idempotent_identifier:
summary: Account(s) not found (with customer Idempotent Identifier)
value:
operation_id: v3_ingest_accounts_close_post
code_id: failed_validation
message: Accounts not found for one or more customers.
errors:
customer_idempotent_identifier:
your_internal_id:
- 275fbbfe-209c-4329-a38b-b324aa386c56
account_not_found_customer_id:
summary: Account(s) not found (with customer ID)
value:
operation_id: v3_ingest_accounts_close_post
code_id: failed_validation
message: Accounts not found for one or more customers.
errors:
customer_ids:
c3339af9-2426-44d4-9c4d-ddb8fd281e23:
- 275fbbfe-209c-4329-a38b-b324aa386c56
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
5XX:
description: An unexpected error occurred on the server side
/ingestion/v3/accounts/reopen:
post:
tags:
- Ingest First Party Data
summary: Reopen Accounts
description: |
Reopen one or more accounts for a given customer. This will remove the account status and `closed_at` fields on the __Retrieve Accounts V3__ response.
If an account is already open, then the request will be ignored and the account is unchanged.
If a 400 response is returned, any accountIDs or customerIDs __not__ defailted in the error response will have been reopened succesfully.
operationId: v3_ingest_accounts_reopen_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReopenAccountsRequest'
examples:
With Customer Idempotent Identifier:
value:
- customer_idempotent_identifier: your_internal_id
account_ids:
- 275fbbfe-209c-4329-a38b-b324aa386c56
With Customer ID:
value:
- customer_id: c3339af9-2426-44d4-9c4d-ddb8fd281e23
account_ids:
- 275fbbfe-209c-4329-a38b-b324aa386c56
responses:
'204':
description: All accounts have been closed successfully. Response has no body.
'400':
description: Bad Request that fails validations on headers and/or payload
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorWihoutErrRequired'
examples:
account_not_found_customer_idempotent_identifier:
summary: Account(s) not found (with customer Idempotent Identifier)
value:
operation_id: v3_ingest_accounts_reopen_post
code_id: failed_validation
message: Accounts not found for one or more customers.
errors:
customer_idempotent_identifier:
your_internal_id:
- 275fbbfe-209c-4329-a38b-b324aa386c56
account_not_found_customer_id:
summary: Account(s) not found (with customer ID)
value:
operation_id: v3_ingest_accounts_reopen_post
code_id: failed_validation
message: Accounts not found for one or more customers.
errors:
customer_ids:
c3339af9-2426-44d4-9c4d-ddb8fd281e23:
- 275fbbfe-209c-4329-a38b-b324aa386c56
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
5XX:
description: An unexpected error occurred on the server side
/v2/ingest/transactions:
post:
tags:
- Ingest First Party Data
summary: Ingest Transactions
description: |
This endpoint should be used to ingest customer transactions into the Bud Platform.
By default, this endpoint is synchronous but can be easily switched to asynchronous using the 'X-Disable-Synchronous' header.
Please refer to the following [guide](https://docs.thisisbud.com/docs/setup_data_enrichment) to ensure you set up First Party Ingestion
correctly for your organisation based on your use case.
We accept a maximum of 1.000 transactions. If this threshold is not respected, a 400 error is returned.
We support the ingestion of transactions for multiple customers as part of the same request.
The detailed location enrichment response is an additional addon, otherwise only tokens are returned
(read more about this in the location [guide](https://docs.thisisbud.com/docs/locations)).
An ingestion request with an empty transaction list and provided transaction windows will be treated as a request to clear persisted transactions in the specified windows.
> 📘 Note:
>
> The enrichment values returned in the synchronous response of this endpoint may differ from those returned when fetching the ingested data from __Retrieve Transactions V2__.
>
> The synchronous response provides an initial enrichment based solely on the submitted transaction data. During asynchronous ingestion, the data is re-enriched using the customer's existing transaction history and additional enrichment services, producing a more accurate and comprehensive result.
operationId: v2_ingest_transactions_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/IngestTransactionsV2ContentType'
- $ref: '#/components/parameters/DisableSynchronous'
- $ref: '#/components/parameters/GenerateTransactionIDs'
- $ref: '#/components/parameters/BudCategorisationModel'
- $ref: '#/components/parameters/NoCustomerHeader'
requestBody:
required: true
content:
application/bud-transaction-v3+json:
schema:
$ref: '#/components/schemas/IngestTransactionsV3Request'
examples:
bud-transaction-v3 Request (with Customer ID):
summary: Ingest Transactions Request (with Customer ID)
value:
- customer_id: c3339af9-2426-44d4-9c4d-ddb8fd281e23
transactions:
- account_id: 275fbbfe-209c-4329-a38b-b324aa386c56
transaction_id: cb49a806-c8f1-47e6-9c1d-5172defe97eb
description: The RSPCA, Southwater
amount: '-10.98'
date_time: '2022-10-10T23:00:00Z'
currency: GBP
status: pending
provider: Monzo
transaction_type:
bud_code: DEB
description: Debit card transaction
suggested_description: The RSPCA, Southwater
counterparty:
name: The RSPCA
identifier: '12345612345678'
- account_id: 275fbbfe-209c-4329-a38b-b324aa386c56
transaction_id: e0f1c489-a4f0-4820-84d1-a86ecb4199b7
description: The RSPCA, Southwater
amount: '-10.98'
date_time: '2022-11-10T23:00:00Z'
currency: GBP
provider: Monzo
transaction_type:
bud_code: DEB
description: Debit card transaction
- account_id: 275fbbfe-209c-4329-a38b-b324aa386c56
transaction_id: d2ea249c-0d1b-4346-b88e-53ec8bc32083
description: Trader Joe's
amount: '-9.98'
date_time: '2022-11-10T23:00:00Z'
currency: USD
provider: Monzo
country_code: US
transaction_windows:
- account_id: 275fbbfe-209c-4329-a38b-b324aa386c56
start: '2022-10-10T23:00:00Z'
end: '2022-11-10T23:00:00Z'
bud-transaction-v3 Request (with Customer Idempotent Identifier):
summary: Ingest Transactions Request (with Customer Idempotent Identifier)
value:
- customer_idempotent_identifier: your_internal_id
transactions:
- account_id: 275fbbfe-209c-4329-a38b-b324aa386c56
transaction_id: cb49a806-c8f1-47e6-9c1d-5172defe97eb
description: The RSPCA, Southwater
amount: '-10.98'
date_time: '2022-10-10T23:00:00Z'
currency: GBP
status: pending
provider: Monzo
transaction_type:
bud_code: DEB
description: Debit card transaction
- account_id: 275fbbfe-209c-4329-a38b-b324aa386c56
transaction_id: e0f1c489-a4f0-4820-84d1-a86ecb4199b7
description: The RSPCA, Southwater
amount: '-10.98'
date_time: '2022-11-10T23:00:00Z'
currency: GBP
provider: Monzo
transaction_type:
bud_code: DEB
description: Debit card transaction
- account_id: 275fbbfe-209c-4329-a38b-b324aa386c56
transaction_id: d2ea249c-0d1b-4346-b88e-53ec8bc32083
description: Trader Joe's
amount: '-9.98'
date_time: '2022-11-10T23:00:00Z'
currency: USD
provider: Monzo
country_code: US
transaction_windows:
- account_id: 275fbbfe-209c-4329-a38b-b324aa386c56
start: '2022-10-10T23:00:00Z'
end: '2022-11-10T23:00:00Z'
responses:
'200':
description: |
The synchronous enrichment request has succeeded and enriched transaction returned.
A new Task has been created to ingest and fully enrich the given transactions.
The generated `task_id` can be used to check the Task's status.
Note: If the endpoint is used synchronously and it's been agreed with Bud to
not store data, the `metadata.task_id` attribute in the response body will be present but empty.
content:
application/json:
schema:
$ref: '#/components/schemas/IngestV2SyncResponse'
examples:
sync enrichment response (with Customer ID):
summary: Synchronous enrichment response (with Customer ID)
value:
operation_id: v2_ingest_transactions_post
data:
- customer_id: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
enriched_transactions:
- transaction_id: another_transaction_id
account_id: another_account_id
description: paypal* specialty coffee london GBR
credit_debit_indicator: debit
status: pending
suggested_description: Specialty Coffee Supplier Ltd.
suggested_logo: http://url/specialty_coffee_supplier_logo.jpeg
transaction_type:
bud_code: DEB
description: PayPal
amount:
value: '10.99'
currency: GBP
date_time: '2022-05-28T10:00:00Z'
tags:
- online
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
tokens:
- value: speciality coffee
confidence: '0.98'
processor:
id: 18f63293-0217-4520-bbf0-071dca7a9d04
slug: paypal
display_name: PayPal
logo: http://url/paypal_logo.jpeg
tokens:
- value: paypal
confidence: '0.92'
transaction_types:
- card
- debit
- transaction_id: a2294cebb45d2a6e0cfc70d270988d8c
account_id: 37c633a71237b9a8282e09587109668e
description: caffe nero 495 ladbroke london gbr
credit_debit_indicator: debit
status: booked
suggested_description: Caffè Nero
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v2/caffnero.jpeg
transaction_type:
bud_code: DEB
description: Debit card transaction
amount:
value: '3.29'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
merchant_category_code: '5814'
enrichments:
categories:
l1:
slug: food_and_drink
confidence: '0.99'
l2:
slug: coffee
confidence: '0.99'
merchant:
id: 4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf
slug: caffnero
display_name: Caffè Nero
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v1/caffnero.jpeg
tokens:
- value: caffe nero
confidence: '1.00'
location:
address:
address_lines:
- 120-122 Ladbroke Grove
- London
- Greater London
- W10 5NE
street_address: 120-122 Ladbroke Grove
city: London
region: Greater London
postal_code: W10 5NE
country: GB
geolocation:
longitude: 51.517301
latitude: -0.209689
tokens:
- gbr
- ladbroke
- london
- transaction_id: cfb6dd1f4c73e1fc36aac756e12644d7
account_id: 37c633a71237b9a8282e09587109668e
description: JOHN SMITH RENT SHARE
credit_debit_indicator: debit
amount:
value: '375.00'
currency: GBP
date_time: '2022-05-30T00:00:00Z'
status: booked
suggested_description: JOHN SMITH RENT SHARE
transaction_type:
bud_code: BAT
description: Bank Transfer
enrichments:
categories:
l1:
slug: mortgage_and_rent
confidence: '0.98'
l2:
slug: rent
confidence: '0.98'
names:
- john smith
metadata:
task_id: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url: /v2/ingest/status/4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url_delay: 500
sync enrichment response (with Customer Idempotent Identifier):
summary: Synchronous enrichment response (with Customer Idempotent Identifier)
value:
operation_id: v2_ingest_transactions_post
data:
- customer_idempotent_identifier: your_internal_id
enriched_transactions:
- transaction_id: another_transaction_id
account_id: another_account_id
description: paypal* specialty coffee london GBR
credit_debit_indicator: debit
status: pending
suggested_description: Specialty Coffee Supplier Ltd.
suggested_logo: http://url/specialty_coffee_supplier_logo.jpeg
transaction_type:
bud_code: DEB
description: PayPal
amount:
value: '10.99'
currency: GBP
date_time: '2022-05-28T10:00:00Z'
tags:
- online
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
tokens:
- value: speciality coffee
confidence: '0.98'
processor:
id: 18f63293-0217-4520-bbf0-071dca7a9d04
slug: paypal
display_name: PayPal
logo: http://url/paypal_logo.jpeg
tokens:
- value: paypal
confidence: '0.92'
transaction_types:
- card
- debit
- transaction_id: a2294cebb45d2a6e0cfc70d270988d8c
account_id: 37c633a71237b9a8282e09587109668e
description: caffe nero 495 ladbroke london gbr
credit_debit_indicator: debit
status: booked
suggested_description: Caffè Nero
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v2/caffnero.jpeg
transaction_type:
bud_code: DEB
description: Debit card transaction
amount:
value: '3.29'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
merchant_category_code: '5814'
enrichments:
categories:
l1:
slug: food_and_drink
confidence: '0.99'
l2:
slug: coffee
confidence: '0.99'
merchant:
id: 4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf
slug: caffnero
display_name: Caffè Nero
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v1/caffnero.jpeg
tokens:
- value: caffe nero
confidence: '1.00'
location:
address:
address_lines:
- 120-122 Ladbroke Grove
- London
- Greater London
- W10 5NE
street_address: 120-122 Ladbroke Grove
city: London
region: Greater London
postal_code: W10 5NE
country: GB
geolocation:
longitude: 51.517301
latitude: -0.209689
tokens:
- gbr
- ladbroke
- london
- transaction_id: cfb6dd1f4c73e1fc36aac756e12644d7
account_id: 37c633a71237b9a8282e09587109668e
description: JOHN SMITH RENT SHARE
credit_debit_indicator: debit
amount:
value: '375.00'
currency: GBP
date_time: '2022-05-30T00:00:00Z'
status: booked
suggested_description: JOHN SMITH RENT SHARE
transaction_type:
bud_code: BAT
description: Bank Transfer
enrichments:
categories:
l1:
slug: mortgage_and_rent
confidence: '0.98'
l2:
slug: rent
confidence: '0.98'
names:
- john smith
metadata:
task_id: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url: /v2/ingest/status/4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url_delay: 500
'202':
description: A new Task has been created to ingest the given transactions. The generated `task_id` can be used to check the Task's status
content:
application/json:
schema:
$ref: '#/components/schemas/IngestV2AsyncResponse'
example:
operation_id: v2_ingest_transactions_post
metadata:
task_id: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url: /v2/ingest/status/4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url_delay: 500
'400':
description: The server will not process the request due to a client error.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BodyDecodeError'
- $ref: '#/components/schemas/ValidationError'
examples:
DecodingError:
summary: Malformed JSON In Payload
value:
operation_id: v2_ingest_transactions_post
code_id: failed_body_decode
message: invalid request body
errors:
decode_error: invalid character 'b' looking for beginning of value
RequestValidationError:
summary: Request Validation Error
value:
operation_id: v2_ingest_transactions_post
code_id: failed_validation
message: validation failure(s) in request payload
errors:
missing_fields:
customers[0].customer_id:
- The customer ID is mandatory
transactions:
- The transactions list is mandatory
PayloadValidationError:
summary: Transaction Validation Error
value:
operation_id: v2_ingest_transactions_post
code_id: failed_validation
message: validation failure(s) in request payload
errors:
missing_fields:
transactions[0]:
- description
- account_id
invalid_fields:
transactions[0]:
- amount
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
'503':
description: An unexpected error occurred on the enrichment server. Sync Only
'504':
description: An unexpected timeout occurred on the enrichment server. Sync Only
5XX:
description: An unexpected error occurred on the server side
callbacks:
FPIIngestSucceededCallback:
'{$request.body#/redirect_url}':
description: |
Should the ingestion task succeed, this callback is sent to your configured 'First Party Data Ingestion Events' webhook URL on the completion of a Ingest Transactions task.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: First Party Ingestion Succeeded Callback
requestBody:
required: true
description: Should the ingestion task succeed, this callback is sent to your configured 'First Party Data Ingestion Events' webhook URL on the completion of a Ingest Transactions task.
content:
application/json:
schema:
$ref: '#/components/schemas/FPIIngestSucceededWebhookBody'
examples:
Success:
description: Successful ingestion
value:
data:
event: first_party_ingester.ingest.succeeded
operation_id: v2_ingest_accounts_post
task_id: 6d37e192-1fdb-407d-82c6-58ee38cb60db
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
FPIIngestFailedCallback:
'{$request.body#/redirect_url}':
description: |
Should the ingestion task fail, this callback is sent to your configured 'First Party Data Ingestion Events' webhook URL on the completion of a Ingest Accounts task.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: First Party Ingestion Failed Callback
requestBody:
required: true
description: Should the ingestion task fail, this callback is sent to your configured 'First Party Data Ingestion Events' webhook URL on the completion of a Ingest Accounts task.
content:
application/json:
schema:
$ref: '#/components/schemas/FPIIngestFailedWebhookBody'
examples:
Success:
description: First Party Ingestion Failed
value:
data:
event: first_party_ingester.ingest.failed
operation_id: v2_ingest_transactions_post
task_id: 6d37e192-1fdb-407d-82c6-58ee38cb60db
result: data_mapping_error
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/ingestion/v3/transactions/book:
post:
tags:
- Ingest First Party Data
summary: Book Transactions
description: |
The Book Transactions endpoint, allows transactions ingested with a `status` of `pending` to set their status to `booked`.
The date_time field indicates the timestamp when the transaction booked. This is reflected in the `date_time` of __Retrieve Transactions V2__.
operationId: v3_ingest_transactions_book_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionSettlementV3Request'
examples:
request_with_customer_id:
summary: Book transactions request (with Customer ID)
value:
- customer_id: c3339af9-2426-44d4-9c4d-ddb8fd281e23
transactions:
- transaction_id: cb49a806-c8f1-47e6-9c1d-5172defe97eb
date_time: '2022-10-11T23:00:00Z'
- transaction_id: e0f1c489-a4f0-4820-84d1-a86ecb4199b7
date_time: '2022-11-11T23:00:00Z'
request_with_customer_idempotent_identifier:
summary: Book transactions request (with Customer Idempotent Identifier)
value:
- customer_idempotent_identifier: your_internal_id
transactions:
- transaction_id: cb49a806-c8f1-47e6-9c1d-5172defe97eb
date_time: '2022-10-11T23:00:00Z'
- transaction_id: e0f1c489-a4f0-4820-84d1-a86ecb4199b7
date_time: '2022-11-11T23:00:00Z'
responses:
'202':
description: |
A new Task has been created to book the given transactions. The generated `task_id` can be used to check the Task's status.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionSettlementV3Response'
example:
operation_id: v3_ingest_transactions_book_post
metadata:
task_id: 444ddd34-7d02-4b57-a55e-63b15b25d453
next_url: /v2/ingest/status/444ddd34-7d02-4b57-a55e-63b15b25d453
next_url_delay: 250
'400':
description: There was something invalid in the request payload. Check the response for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorWihoutErrRequired'
example:
operation_id: v3_ingest_transactions_book_post
code_id: failed_body_decode
message: Unable to parse request.
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
5XX:
description: An unexpected error occurred on the server side
callbacks:
TransactionBookCompletedCallback:
https://example.com/booked:
description: |
This callback is sent to your pre-configured webhook URL for the `first_party_ingester.transactions.booked` event.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Transaction Book Completed Callback
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionSettlementV3WebookBody'
example:
data:
event: first_party_ingester.transactions.booked
operation_id: v3_ingest_transactions_book_post
status: Completed
task_id: 444ddd34-7d02-4b57-a55e-63b15b25d453
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/ingestion/v3/transactions/decline:
post:
tags:
- Ingest First Party Data
summary: Decline Transactions
description: |
The Decline Transactions endpoint, allows transactions ingested with a `status` of `pending` to set their status to `declined`.
The date_time field indicates the timestamp when the transaction declined. This is reflected in the `date_time` of __Retrieve Transactions V2__.
operationId: v3_ingest_transactions_decline_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionSettlementV3Request'
examples:
request_with_customer_id:
summary: Decline transactions request (with Customer ID)
value:
- customer_id: c3339af9-2426-44d4-9c4d-ddb8fd281e23
transactions:
- transaction_id: cb49a806-c8f1-47e6-9c1d-5172defe97eb
date_time: '2022-10-11T23:00:00Z'
- transaction_id: e0f1c489-a4f0-4820-84d1-a86ecb4199b7
date_time: '2022-11-11T23:00:00Z'
request_with_customer_idempotent_identifier:
summary: Decline transactions request (with Customer Idempotent Identifier)
value:
- customer_idempotent_identifier: your_internal_id
transactions:
- transaction_id: cb49a806-c8f1-47e6-9c1d-5172defe97eb
date_time: '2022-10-11T23:00:00Z'
- transaction_id: e0f1c489-a4f0-4820-84d1-a86ecb4199b7
date_time: '2022-11-11T23:00:00Z'
responses:
'202':
description: |
A new Task has been created to decline the given transactions. The generated `task_id` can be used to check the Task's status.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionSettlementV3Response'
example:
operation_id: v3_ingest_transactions_decline_post
metadata:
task_id: 444ddd34-7d02-4b57-a55e-63b15b25d453
next_url: /v2/ingest/status/444ddd34-7d02-4b57-a55e-63b15b25d453
next_url_delay: 250
'400':
description: Payload request was invalid. Check the response for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorWihoutErrRequired'
example:
operation_id: v3_ingest_transactions_decline_post
code_id: failed_body_decode
message: Unable to parse request.
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
5XX:
description: An unexpected error occurred on the server side
callbacks:
TransactionDeclineCompletedCallback:
https://example.com/declined:
description: |
This callback is sent to your pre-configured webhook URL for the `first_party_ingester.transactions.declined` event.
post:
security: []
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Transaction Book Completed Callback
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionSettlementV3WebookBody'
example:
data:
event: first_party_ingester.transactions.declined
operation_id: v3_ingest_transactions_decline_post
status: Completed
task_id: 444ddd34-7d02-4b57-a55e-63b15b25d453
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/ingestion/v3/tasks/{task_id}:
get:
tags:
- Ingest First Party Data
summary: Retrieve Ingestion Task Status
description: |
Check the status of an ingest request. Please note that this works for both the Ingest Transactions endpoints And Ingest Accounts endpoints.
Reports status of the ingestion task, with details for each subtask (1 per customer).
operationId: v3_ingest_status_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/IngestStatusV3Response'
examples:
Pending Task (with Customer ID):
summary: Pending Task (with Customer ID)
value:
operation_id: v3_ingest_status_get
data:
- customer_id: f89ae931-8cb3-4352-ac9e-4e4572fe5026
status: Pending
metadata:
task_id: 3d592efc-493a-4548-8008-f738fd0877ab
status: Pending
next_url: /ingestion/v3/tasks/3d592efc-493a-4548-8008-f738fd0877ab
next_url_delay: 500
Successful Task (with Customer ID):
summary: Successful Task (with Customer ID)
value:
operation_id: v3_ingest_status_get
data:
- customer_id: f89ae931-8cb3-4352-ac9e-4e4572fe5026
status: Completed
result: success
metadata:
task_id: 3d592efc-493a-4548-8008-f738fd0877ab
status: Completed
result: success
ingest_request_id: 213be00c-60ce-9af5-95ab-d450a9ffc2ac
ingest_route: v2_ingest_transactions_post
ingest_schema: application/bud-transaction-v3+json
Failed Task (with Customer ID):
summary: Failed Task (with Customer ID)
value:
operation_id: v3_ingest_status_get
data:
- customer_id: f89ae931-8cb3-4352-ac9e-4e4572fe5026
status: Failed
result: data_mapping_error
error:
accounts[0].currency: 'unexpected currency code: GlkjlkjBP, expected ISO-4217 currency code'
metadata:
task_id: 3d592efc-493a-4548-8008-f738fd0877ab
status: Failed
result: data_mapping_error
Pending Task (with Customer Idempotent Identifier):
summary: Pending Task (with Customer Idempotent Identifier)
value:
operation_id: v3_ingest_status_get
data:
- customer_idempotent_identifier: your_internal_id
status: Pending
metadata:
task_id: 3d592efc-493a-4548-8008-f738fd0877ab
status: Pending
next_url: /ingestion/v3/tasks/3d592efc-493a-4548-8008-f738fd0877ab
next_url_delay: 500
Successful Task (with Customer Idempotent Identifier):
summary: Successful Task (with Customer Idempotent Identifier)
value:
operation_id: v3_ingest_status_get
data:
- customer_idempotent_identifier: your_internal_id
status: Completed
result: success
metadata:
task_id: 3d592efc-493a-4548-8008-f738fd0877ab
status: Completed
result: success
ingest_request_id: 213be00c-60ce-9af5-95ab-d450a9ffc2ac
ingest_route: v2_ingest_transactions_post
ingest_schema: application/bud-transaction-v3+json
Failed Task (with Customer Idempotent Identifier):
summary: Failed Task (with Customer Idempotent Identifier)
value:
operation_id: v3_ingest_status_get
data:
- customer_idempotent_identifier: your_internal_id
status: Failed
result: data_mapping_error
error:
accounts[0].currency: 'unexpected currency code: GlkjlkjBP, expected ISO-4217 currency code'
metadata:
task_id: 3d592efc-493a-4548-8008-f738fd0877ab
status: Failed
result: data_mapping_error
'401':
description: Unauthorized (BearerToken in 'Authorization' header fails the authentication)
'404':
description: The task couldn't be found
content:
application/json:
schema:
$ref: '#/components/schemas/TaskNotFoundError'
example:
operation_id: v2_ingest_status_get
code_id: task_not_found
message: Task ID [6c7d06a7-5b40-4556-91d4-6b6d1a7db3f1] does not exist or it has expired
'405':
description: The request uses an unexpected HTTP method
5XX:
description: An unexpected error occurred on the server side
/platform/v3/customers:
post:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Create Customer V3
description: |
This endpoint is used to create a new Customer in order for them to consume the Bud services.
When we refer to a Customer, we're talking about the end-user of yours and Bud's technology. Customer entities in Bud have unique identifiers and this is used to store the customer data on the Bud platform.
For more information on how to manage your Bud Customers, please, refer to the following [guide](https://docs.thisisbud.com/docs/setup-customers)
> 📘 Note:
>
> By specifying a `client_metadata.idempotent_identifier` value, Bud will associate that identifier to a Customer,
> and in future Bud will return the same Customer entity everytime we receive the same `idempotent_identifier` value.
>
> This allows you to associate your internal resource to the concept of the Bud Customer.
>
> On subsequent requests for a customer with a given `idempotent_identifier`, Bud will return a 200 status code instead of a 201.
>
> Please, make sure the `idempotent_identifier` is immutable on your application.
operationId: platform_v3_customers_post
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: false
content:
application/json:
schema:
properties:
customer_context:
$ref: '#/components/schemas/CustomerContextRequest'
client_metadata:
$ref: '#/components/schemas/ClientMetadata'
example:
customer_context:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
client_metadata:
idempotent_identifier: your_internal_id
responses:
'200':
description: Returns the existing customer matching the idempotent identifier.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerCreateV3Response'
example:
operation_id: platform_v3_customers_post
data:
customer_id: 360e5821-4f18-4077-83f4-c9a7c1768bea
customer_context:
type: personal
region: GB
locale: en-GB
host_secret: true
models:
categorisation: uk-v2
client_metadata:
idempotent_identifier: your_internal_id
metadata:
created_at: '2023-01-01T07:02:11Z'
'201':
description: The resource has been successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerCreateV3Response'
example:
operation_id: platform_v3_customers_post
data:
customer_id: 360e5821-4f18-4077-83f4-c9a7c1768bea
customer_context:
type: personal
region: GB
locale: en-GB
host_secret: true
models:
categorisation: uk-v2
client_metadata:
idempotent_identifier: your_internal_id
metadata:
created_at: '2023-01-01T07:02:11Z'
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: platform_v3_customers_post
code_id: failed_validation
message: invalid body
errors:
body: invalid character 'a' looking for beginning of object key string
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
get:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Retrieve Customers V3
description: |
This endpoint is used to list customers associated with the current project.
Customers are listed ordered by their ID. Deleted customers will not be included in the list.
The list of customers can be filtered by creation date with the `date_from` and `date_to` query parameters, which expect dates in the RFC3339 format.
If more results pages are available, the response metadata object will contain a `next_page_token` field which can be used to fetch the next page of results. The token should be provided in the `page_token` query parameter for subsequent requests.
For more information on how to manage your Bud Customers, please, refer to the following [guide](https://docs.thisisbud.com/docs/setup-customers)
operationId: platform_v3_customers_get
parameters:
- $ref: '#/components/parameters/ClientId'
- in: query
name: date_from
schema:
type: string
example: '2022-05-28T00:00:00Z'
description: |
Date (RFC3339) to filter customers created on or after which. To maintain backwards compatibility, dates in the format (YYYY-MM-DD) can also be used and will be assumed to be UTC.
- in: query
name: date_to
schema:
type: string
example: '2022-05-29T00:00:00Z'
description: |
Date (RFC3339) to filter customers created on or before which. To maintain backwards compatibility, dates in the format (YYYY-MM-DD) can also be used and will be assumed to be UTC. Uses the current date by default.
- name: page_size
in: query
schema:
type: integer
minimum: 1
maximum: 1000
description: The number of results to return per page. Defaults to 200.
- name: page_token
in: query
schema:
type: string
description: |
The token required to fetch a specific page of results. Provided by the next_page_token field in the previous request.
- name: idempotent_identifier
in: query
schema:
type: string
description: |
Filter by the internal client identifier provided in the `client_metadata` object when creating the customer in __Create Customer V3__. Only one customer will be returned if one is found with the given identifier.
responses:
'200':
description: Returns a list of customers.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomersGetAllV3Response'
example:
operation_id: platform_v3_customers_get
data:
- customer_id: acbff0b9-299c-4065-b933-4a991e17da6d
idempotent_identifier: acbff0b9-299c-4065-b933-4a991e17da6d
created_at: 2019-02-27T06:11:57+0000
- customer_id: ebb50ae5-8c5c-4205-9b61-e93ce84eb467
created_at: 2019-02-27T06:11:57+0000
metadata:
next_page_token: eyJwYWdlX3NpemUiOjIsInBhZ2UiOjF9
results: 2
'400':
description: The request contains an invalid parameter.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: platform_v3_customers_get_all
code_id: bad_request
message: invalid page token
errors:
page_token:
- Failed to parse page token
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/platform/v3/customers/batch:
post:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Create Customers V3 (Batch)
description: |
This endpoint is used to create a batch of new Customers in order for them to consume the Bud services.
For more information on Customers in the Bud platform, please refer to our handy [guide](https://docs.thisisbud.com/docs/setup-customers).
operationId: platform_v3_customers_batch_post
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomersV3BatchPayload'
example:
number_of_customers: 2
customer_context:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
responses:
'201':
description: The resource has been successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomersV3BatchResponse'
example:
operation_id: platform_v3_customers_batch_post
data:
- customer_id: 360e5821-4f18-4077-83f4-c9a7c1768bea
customer_context:
type: personal
region: GB
locale: en-GB
host_secret: true
models:
categorisation: uk-v2
- customer_id: 8d3e9cd4-fa92-4252-8725-9b20af307b76
customer_context:
type: personal
region: GB
locale: en-GB
host_secret: true
models:
categorisation: uk-v2
metadata:
created_at: '2023-01-01T07:02:11Z'
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: customers_create
code_id: failed_validation
message: Failed validation.
errors:
client_id: This value should not be blank
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/platform/v3/customers/{customer_id}:
delete:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Remove Customer V3
description: This endpoint is used to delete an existing Customer. Calling this endpoint initiates deleting all data relating to a customer returning a task id that can be used to check the status of the delete task.
operationId: platform_v3_customers_delete
parameters:
- in: path
name: customer_id
schema:
type: string
required: true
description: The customer identifier.
- $ref: '#/components/parameters/ClientId'
responses:
'202':
description: The request was successfully accepted for processing and details of the task was returned.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerDeleteV3Response'
example:
operation_id: platform_v3_customers_delete
data:
task_id: e74efdd2-bd44-42b0-9562-106286664966
metadata:
status: Pending
next_url: /v3/customers/45cecf3f-8436-4b57-8953-cfdfbd2620d4/e74efdd2-bd44-42b0-9562-106286664966
next_url_delay: 50
'401':
description: An unauthenticated request was received.
'404':
description: The resource was not found.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/platform/v3/customers/idempotent-identifier/{customer_idempotent_identifier}:
delete:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Remove Customer By Idempotent Identifier V3
description: This endpoint is used to delete an existing Customer. Calling this endpoint initiates deleting all data relating to a customer returning a task id that can be used to check the status of the delete task.
operationId: platform_v3_customers_idempotent_identifier_delete
parameters:
- in: path
name: customer_idempotent_identifier
schema:
type: string
required: true
description: The internal client identifier, provided in the client_metadata object when creating the customer in Create Customer V3.
- $ref: '#/components/parameters/ClientId'
responses:
'202':
description: The request was successfully accepted for processing and details of the task was returned.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerDeleteV3Response'
example:
operation_id: platform_v3_customers_idempotent_identifier_delete
data:
task_id: e74efdd2-bd44-42b0-9562-106286664966
metadata:
status: Pending
next_url: /v3/customers/45cecf3f-8436-4b57-8953-cfdfbd2620d4/e74efdd2-bd44-42b0-9562-106286664966
next_url_delay: 50
'401':
description: An unauthenticated request was received.
'404':
description: The resource was not found.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/platform/v3/customers/{customer_id}/{task_id}:
get:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Retrieve Remove Customer V3 Status
description: |
Check the status and get the result of a Remove Customer V3 task.
operationId: platform_v3_customers_delete_status
parameters:
- in: path
name: customer_id
schema:
type: string
required: true
description: The customer identifier.
- $ref: '#/components/parameters/TaskId'
- $ref: '#/components/parameters/ClientId'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerDeleteV3StatusResponse'
examples:
complete:
summary: Completed
value:
operation_id: platform_v3_customers_delete_status
data:
task_id: e74efdd2-bd44-42b0-9562-106286664966
result: success
metadata:
status: Completed
pending:
summary: Pending
value:
operation_id: platform_v3_customers_delete_status
data:
status: Pending
task_id: 16fa0748-8a6b-455b-9be9-30ae257965d8
metadata:
status: Pending
next_url: /v3/customers/45cecf3f-8436-4b57-8953-cfdfbd2620d4/e74efdd2-bd44-42b0-9562-106286664966
next_url_delay: 50
failed:
summary: Failed
value:
operation_id: platform_v3_customers_delete_status
data:
task_id: e74efdd2-bd44-42b0-9562-106286664966
result: failed
metadata:
status: Failed
'401':
description: An unauthenticated request was received.
'404':
description: The resource was not found.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/v1/customers:
post:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Create Customer
deprecated: true
description: |
This endpoint is used to create a new Customer in order for them to consume the Bud services.
**Please note: this endpoint is now deprecated, please migrate to using the POST /v2/customers endpoint.**
operationId: customers_create_v1
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: false
content:
application/json:
schema:
properties:
customer_context:
$ref: '#/components/schemas/CustomerContext'
example:
customer_context:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
responses:
'201':
description: The resource has been successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerCreateResponse'
example:
operation_id: customers_create
data:
customer_id: 360e5821-4f18-4077-83f4-c9a7c1768bea
customer_secret: 63ae14a67e5cf8c8f7bf5376479d13e9
customer_context:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: customers_create
code_id: failed_validation
message: Failed validation.
errors:
client_id: This value should not be blank
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/v2/customers:
post:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Create Customer(s)
deprecated: true
description: This endpoint is used to create one or many new Customers, in order for them to consume the Bud services.
operationId: customers_create_v2
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomersPayload'
example:
number_of_customers: 3
customer_context:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
responses:
'201':
description: The resource has been successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomersCreateResponse'
examples:
Multiple Customers:
value:
operation_id: v2_customers_post
data:
- customer_id: 360e5821-4f18-4077-83f4-c9a7c1768bea
customer_secret: 63ae14a67e5cf8c8f7bf5376479d13e9
customer_context:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
- customer_id: 7788d43e-4eb1-11eb-ae93-0242ac130002
customer_secret: 63ae14a67e5cf8c8f7bf5376479d13e5
customer_context:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
- customer_id: 8e4b6f88-4eb1-11eb-ae93-0242ac130002
customer_secret: a951d12bf19e2874254cb2833dc5a8c3
customer_context:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
metadata:
results: 3
Single Customer:
value:
operation_id: v2_customers_post
data:
- customer_id: 360e5821-4f18-4077-83f4-c9a7c1768bea
customer_secret: 63ae14a67e5cf8c8f7bf5376479d13e9
customer_context:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
metadata:
results: 1
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v2_customers_post
code_id: failed_validation
message: Failed validation.
errors:
client_id: This value should not be blank
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/v1/customers/{customer_id}:
delete:
deprecated: true
security:
- OAuth2: []
tags:
- Manage Customers
summary: Remove Customer
description: |
This endpoint is used to delete an existing Customer. Calling this deletes all data associated with the customer including any Open Banking Consents.
If the customer with the given ID does not exist or has already been deleted, a 404 error is returned.
operationId: customers_delete
parameters:
- $ref: '#/components/parameters/PathCustomerID'
- $ref: '#/components/parameters/ClientId'
responses:
'204':
description: The request was successfully processed and no content is returned.
'401':
description: An unauthenticated request was received.
'404':
description: No customer was found with the given ID.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/v1/customers/{customer_id}/context:
get:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Retrieve Customer Context
description: Retrieve the customer level context, i.e. a set of parameters that defines their language, region and their customer type.
operationId: v1_customer_context_get
parameters:
- $ref: '#/components/parameters/PathCustomerID'
- $ref: '#/components/parameters/ClientId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerContextResponse'
example:
operation_id: v1_customer_context_get
data:
type: personal
region: GB
locale: en-GB
models:
categorisation: uk-v2
'401':
description: An unauthenticated request was received.
'404':
description: The resource was not found.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
put:
security:
- OAuth2: []
tags:
- Manage Customers
summary: Update Customer Context
description: |
Updates the customer context.
All three body parameters (region, locale, and models) will overwrite any existing values.
If a parameter is not provided, it's corresponding context field will be set to empty.
operationId: v1_customer_context_put
parameters:
- $ref: '#/components/parameters/PathCustomerID'
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCustomerContextRequest'
example:
region: GB
locale: en-GB
models:
categorisation: uk-v2
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCustomerContextResponse'
example:
operation_id: v1_customer_context_put
data:
region: GB
locale: en-GB
models:
categorisation: uk-v2
'400':
description: Request recieved was invalid.
'401':
description: An unauthenticated request was received.
'404':
description: The resource was not found.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/resources/v2/categories/models:
get:
tags:
- Enrichment Resources
summary: Retrieve Available Categorisation Models V2
description: Retrieve the available Bud categorisation models.
operationId: resources_v2_models_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetModelsResponse'
example:
operation_id: resources_v2_models_get
data:
- name: uk-v2
description: 'A UK categorisation model. This model can be used for the following use cases: affordability assessments, collections assessments, affordability monitoring, customer engagement and product recommendations.'
'400':
description: The request contains an invalid payload.
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/resources/v2/categories:
get:
tags:
- Enrichment Resources
summary: Retrieve Categories V2
description: Retrieve a list of primary and secondary categories supported by Bud's categorisation model.
operationId: resources_v2_categories_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- in: query
name: format
schema:
type: string
enum:
- map
- flat
default: flat
description: |
Determines if the response will be structured:
- As a flat object where all categories and subcategories are listed separately under different fields. See the example response `Flat Response`.
- As a map where all categories are listed as objects themselves with their respective subcategories listed in fields within the category objects. See the example response `Map Response`.
- in: query
name: model
schema:
type: string
description: |
The name of the model for which categories should be returned. See the *List Categorisation Models V2* endpoint for available model names.
- in: query
name: label
schema:
type: string
description: Filter out categories that do not have the specified label. If unset, endpoint will include all labels
example: essential
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetCategoriesV2Response'
examples:
Category List (flat):
value:
operation_id: resources_v2_categories_get
data:
categories:
- travel
- banking
subcategories:
- holiday_and_travel_expenses
- flights_and_airport_expenses
- other_travel
- bank_fees_and_currency_exchange
- other_banking
- cash_withdrawals
- refunds_and_reversals
- overdraft_fees
- unpaid_transactions
metadata:
model:
name: uk-v2
description: 'A UK categorisation model. This model can be used for the following use cases: affordability assessments, collections assessments, affordability monitoring, customer engagement and product recommendations.'
Category Map:
value:
operation_id: resources_v2_categories_get
data:
- name: travel
subcategories:
- name: holiday_and_travel_expenses
labels:
- travel
- name: flights_and_airport_expenses
- name: other_travel
labels:
- nonessential
- name: banking
subcategories:
- name: bank_fees_and_currency_exchange
labels:
- essential
- name: other_banking
labels:
- nonessential
- name: cash_withdrawals
labels:
- nonessential
- name: interest
labels:
- essential
- name: refunds_and_reversals
- name: overdraft_fees
labels:
- essential
- name: unpaid_transactions
labels:
- essential
metadata:
model:
name: uk-v2
description: 'A UK categorisation model. This model can be used for the following use cases: affordability assessments, collections assessments, affordability monitoring, customer engagement and product recommendations.'
'400':
description: The request contains an invalid payload.
'401':
description: Unauthorised request
'404':
description: Model not found
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/aggregations/v2/totals/categories:
get:
tags:
- Enrichment Totals
summary: Retrieve Category Totals V2
description: |
Provides a customer’s total income and expenditure for each l1 and l2 category, over a given time period.
L1 and l2 categories can be filtered using the category query parameter.
Example:
- 'shopping'
- 'shopping.groceries'
Each income and expenditure total is separated by currency, as we cannot sum totals in different currencies.
operationId: v2_category_totals_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/CategoryTotalsQueryFromTimestamp'
- $ref: '#/components/parameters/CategoryTotalsQueryToTimestamp'
- $ref: '#/components/parameters/QueryBudCategory'
- $ref: '#/components/parameters/QueryExcludeBudCategory'
- $ref: '#/components/parameters/QueryCurrency'
- $ref: '#/components/parameters/QueryAccountID'
- in: query
name: include_l2
schema:
type: boolean
example: true
description: Whether to include the L2 categories in result. Defaults to false.
- $ref: '#/components/parameters/CategoryTotalsQueryCategoryFilter'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoriesTotalV2Response'
example:
operation_id: v2_category_totals_get
data:
- name: shopping
credit_total:
- amount:
value: '357.90'
currency: GBP
transaction_count: 1
debit_total:
- amount:
value: '397.80'
currency: GBP
transaction_count: 2
l2_totals:
- name: clothing
credit_total:
- amount:
value: '357.90'
currency: GBP
transaction_count: 1
debit_total:
- amount:
value: '397.80'
currency: GBP
transaction_count: 2
metadata:
from: '2023-05-21T07:20:50.52Z'
to: '2023-06-21T07:20:50.52Z'
credit_total:
- amount:
value: '357.90'
currency: GBP
transaction_count: 1
debit_total:
- amount:
value: '397.80'
currency: GBP
transaction_count: 2
'400':
description: The request contains an invalid payload.
'401':
description: An unauthenticated request was received
5XX:
description: An unexpected error occurred on the server side
/aggregations/v2/totals/categories/trends:
get:
tags:
- Enrichment Totals
summary: Retrieve Category Totals Trends
description: |
Provides category totals for desired categories over a given time period of time with a given granularity.
L1 and l2 categories can be filtered using the category query parameter.
Example:
- 'shopping'
- 'shopping.groceries'
Each income and expenditure total is separated by currency, as we cannot sum totals in different currencies.
Can be used for producing graphs of category totals over time.
operationId: v2_category_totals_trends_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/CategoryTotalsQueryFromTimestamp'
- $ref: '#/components/parameters/CategoryTotalsQueryToTimestamp'
- $ref: '#/components/parameters/QueryAccountID'
- $ref: '#/components/parameters/QueryCurrency'
- $ref: '#/components/parameters/QueryBudCategory'
- $ref: '#/components/parameters/QueryExcludeBudCategory'
- in: query
name: include_l2
schema:
type: boolean
example: true
description: Whether to include the L2 categories in result. Defaults to false.
- in: query
name: granularity
schema:
type: string
example: monthly
description: |
Specifies in what interval the balance over time should be retrieved.
Currently supported values include (but are not necessarily limited to):
- `daily`
- `weekly`
- `biweekly`
- `monthly`
- `quarterly`
- `six_monthly`
- `annually`
Defaults to `monthly`.
- $ref: '#/components/parameters/CategoryTotalsQueryCategoryFilter'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoriesTotalTrendsV2Response'
example:
operation_id: v2_category_totals_get
data:
- from: '2023-05-21T07:20:50.52Z'
to: '2023-05-21T07:20:50.52Z'
data:
- name: shopping
credit_total:
- amount:
value: '357.90'
currency: GBP
transaction_count: 1
debit_total:
- amount:
value: '397.80'
currency: GBP
transaction_count: 2
l2_totals:
- name: clothing
credit_total:
- amount:
value: '357.90'
currency: GBP
transaction_count: 1
debit_total:
- amount:
value: '397.80'
currency: GBP
transaction_count: 2
'400':
description: The request contains an invalid payload.
'401':
description: An unauthenticated request was received
5XX:
description: An unexpected error occurred on the server side
/aggregations/v2/totals/essential-statistics:
get:
tags:
- Enrichment Totals
summary: Retrieve Statistics For Essential Total Spend
description: |
Provides a few useful statistics which allow you to quickly see a customers total essential and non essential spend.
Will also allow you to see this spend as a percentage of overall spend.
operationId: aggregations_v2_totals_essential_statistics_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/CategoryTotalsQueryFromTimestamp'
- $ref: '#/components/parameters/CategoryTotalsQueryToTimestamp'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EssentialSpendStatisticsResponse'
example:
operation_id: aggregations_v2_totals_essential_statistics_get
data:
essential_spend:
- transaction_count: 4
amount:
currency: GBP
value: '538.69'
nonessential_spend:
- transaction_count: 2
amount:
currency: GBP
value: '143.00'
essential_percentage_overall_spend:
- percentage: 79.02272293857912
currency: GBP
nonessential_percentage_overall_spend:
- percentage: 20.977277061420878
currency: GBP
metadata:
from: '2020-01-01T00:00:00Z'
to: '2025-01-01T00:00:00Z'
'400':
description: The request contains an invalid payload.
'401':
description: An unauthenticated request was received
5XX:
description: An unexpected error occurred on the server side
/v2/merchants/totals:
get:
tags:
- Enrichment Totals
summary: Retrieve Merchant Totals V2
description: |
Provides a customer’s total debit and credit amounts for each merchant.
operationId: v2_merchants_totals_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- in: header
name: X-From
required: false
schema:
type: string
example: '2022-02-28'
description: |
The date from when results are to be retrieved in the format [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html).
When ommited from the request, a default value of 30 days from before today's date will be used.
Example: `2022-02-28`
- in: header
name: X-To
required: false
schema:
type: string
example: '2022-01-28'
description: |
The date up to when results are to be retrieved in the format [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html).
When ommited from the request, a default value of today's date will be used.
Example: `2022-01-28`
- $ref: '#/components/parameters/MerchantsTotalsIncludeCategories'
- $ref: '#/components/parameters/MerchantsTotalsExcludeCategories'
responses:
'200':
description: The request was successfully processed
content:
application/json:
schema:
$ref: '#/components/schemas/MerchantTotalsResponseV2'
example:
operation_id: v2_merchants_totals_get
data:
- merchant:
id: tesco
logo: https://thisisbud.com/merchants/tesco.png
name: Tesco
total_debit:
value: '130.23'
currency: GBP
total_credit:
value: '12.21'
currency: GBP
transaction_count: 8
credit_transaction_count: 1
debit_transaction_count: 7
- merchant:
id: waitrose
logo: https://thisisbud.com/merchants/waitrose.png
name: Waitrose
total_debit:
value: '240.23'
currency: GBP
total_credit:
value: '6.56'
currency: GBP
transaction_count: 10
credit_transaction_count: 1
debit_transaction_count: 9
metadata:
from: '2018-01-01'
to: '2018-01-17'
credit_total:
- transaction_count: 2
amount:
currency: GBP
value: '18.77'
debit_total:
- transaction_count: 16
amount:
currency: GBP
value: '370.46'
results: 2
'204':
description: No transactions found
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v2_merchants_totals_get
code_id: failed_validation
message: Failed validation
errors:
client_id: This value should not be blank
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/financial/v3/accounts:
get:
tags:
- Retrieve Financial Data
summary: Retrieve Accounts V3
description: |
Retrieves a list of a customer's connected accounts. The result can be filtered using the parameters outlined below.
> 📘 Note: > > For more information on the Account object, please refer to our handy [guide](https://docs.thisisbud.com/docs/accounts).
operationId: financial_v3_accounts_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/QueryCurrency'
- $ref: '#/components/parameters/QueryProvider'
- in: query
name: account_type
schema:
type: string
example: current_account
description: |
Use this parameter to filter the results returned on the `account_type` associated with each result. Multiple values are accepted. If this parameter is not provided then results of any `account_type` will be returned.
Currently supported values include (but are not necessarily limited to):
- `auto_loan`
- `boat_loan`
- `brokerage`
- `business_loan`
- `certificate_of_deposit`
- `charge_card`
- `checking_account`
- `credit_card`
- `current_account`
- `disability_insurance`
- `e_money`
- `health_insurance`
- `home_equity_loan`
- `investment`
- `ira`
- `liability_insurance`
- `life_insurance`
- `line_of_credit`
- `loan`
- `money_market`
- `mortgage`
- `other`
- `personal_loan`
- `pre_paid_card`
- `property_insurance`
- `roth`
- `rv_loan`
- `savings`
- `student_loan`
- `travel_insurance`
- `vehicle_insurance`
- in: query
name: usage_type
schema:
type: string
example: personal
description: |
Use this parameter to filter the results returned on the `usage_type` associated with each result. Multiple values are accepted. If this parameter is not provided then results of any `usage_type` will be returned.
Currently supported values include (but are not necessarily limited to):
- `personal`
- `business`
- in: query
name: holder_relationship_type
schema:
type: string
example: joint
description: |
Use this parameter to filter the results returned on the `holder_relationship_type` associated with each result. Multiple values are accepted. If this parameter is not provided then results of any `holder_relationship_type` will be returned.
Currently supported values include (but are not necessarily limited to):
- `sole`
- `joint`
- `delegate`
- `unknown`
- in: query
name: include_all_balances
schema:
type: boolean
example: true
description: |
Use this parameter to include all balances associated with each account. If this parameter is not provided then only the pending and booked balance will be returned where available.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAccountsV3Response'
examples:
Account:
value:
operation_id: financial_v3_accounts_get
data:
- account_id: RxsYshVGded4JeilkXgWKdXA
currency: GBP
holders:
- name: David Smith
relationship: unknown
account_name: My Current Account
suggested_name: My Current Account
account_type: current_account
usage_type: personal
account_category: depository
provider: BankOfBud
provider_display_name: Bank Of Bud
provider_logo: https://assets.thisisbud.com/merchants/BankOfBud.png
opening_date_time: '2019-10-01T00:00:00Z'
identifiers:
uk_sort_code: '126432'
uk_account_number: '31510604'
balances:
booked:
date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
credit_debit_indicator: credit
pending:
date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
credit_debit_indicator: credit
credit_lines:
limit:
date: '2023-01-12T00:00:00Z'
amount:
value: '1000.00'
currency: GBP
- account_id: 97282bfc-84a5-44f6-9a3e-399903f92f7a
currency: GBP
holders:
- name: Sarah Jones
relationship: unknown
suggested_name: Current Account 0603
account_type: current_account
usage_type: personal
account_category: depository
status: closed
closed_at: '2023-01-11T00:00:00Z'
provider: BankOfBud
provider_display_name: Bank Of Bud
provider_logo: https://assets.thisisbud.com/merchants/BankOfBud.png
identifiers:
uk_sort_code: '126433'
uk_account_number: '21510603'
balances:
booked:
date: '2023-01-11T00:00:00Z'
amount:
value: '2552.61'
currency: GBP
credit_debit_indicator: credit
pending:
date: '2023-01-11T00:00:00Z'
amount:
value: '2552.61'
currency: GBP
credit_debit_indicator: credit
credit_lines:
limit:
date: '2023-01-11T00:00:00Z'
amount:
value: '1000.00'
currency: GBP
metadata:
parameters:
currencies:
- GBP
results: 2
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
CustomerID Not Sent:
value:
operation_id: financial_v3_accounts_get
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id: not present
CustomerID and CustomerSecret Not Sent:
value:
operation_id: financial_v3_accounts_get
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id:
- not present
X-Customer-Secret:
- not present
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/financial/v3/accounts/{account_id}:
get:
tags:
- Retrieve Financial Data
summary: Retrieve Account By ID V3
description: |
Retrieves a customer's connected account by its ID.
> 📘 Note: > > For more information on the Account object, please refer to our handy [guide](https://docs.thisisbud.com/docs/accounts).
operationId: financial_v3_accounts_account_id_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/PathAccountID'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveAccountByIDV3Response'
examples:
Account:
value:
operation_id: financial_v3_accounts_account_id_get
data:
account_id: RxsYshVGded4JeilkXgWKdXA
currency: GBP
holders:
- name: David Smith
relationship: unknown
suggested_name: Current Account 0604
account_type: current_account
provider: BankOfBud
identifiers:
uk_sort_code: '126432'
uk_account_number: '31510604'
balance:
booked:
date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
credit_debit_indicator: debit
credit_lines:
limit:
date: '2023-01-12T00:00:00Z'
amount:
value: '1000.00'
currency: GBP
metadata:
parameters:
account_id: RxsYshVGded4JeilkXgWKdXA
results: 1
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
CustomerID Not Sent:
value:
operation_id: financial_v3_accounts_account_id_get
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id: not present
CustomerID and CustomerSecret Not Sent:
value:
operation_id: financial_v3_accounts_account_id_get
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id:
- not present
X-Customer-Secret:
- not present
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/financial/v3/accounts/transaction-dates:
get:
tags:
- Retrieve Financial Data
summary: Retrieve Account Transaction Dates
description: |
Retrieves a summary listing the first and last transaction per customer's accounts.
operationId: financial_v3_accounts_transaction_dates_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAccountTransactionDatesV3Response'
examples:
Account:
value:
operation_id: financial_v3_accounts_transaction_dates_get
data:
- account_id: 1da3ba98-07f7-469e-b7e7-3a7cfcf19b82
first_transaction_date: '2024-12-08T02:59:00Z'
last_transaction_date: '2025-12-02T02:00:00Z'
- account_id: 6aa9a396-75ca-48da-9dba-5f4094cb3a83
first_transaction_date: '2024-12-01T02:00:00Z'
last_transaction_date: '2025-12-01T02:00:00Z'
metadata:
results: 2
first_transaction_date: '2024-12-01T02:00:00Z'
last_transaction_date: '2025-12-02T02:00:00Z'
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
CustomerID Not Sent:
value:
operation_id: financial_v3_accounts_get
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id: not present
CustomerID and CustomerSecret Not Sent:
value:
operation_id: financial_v3_accounts_get
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id:
- not present
X-Customer-Secret:
- not present
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/financial/v3/balances:
get:
tags:
- Retrieve Financial Data
summary: Retrieve Balances Over Time V3
description: |
List the balances of each bank account for a customer across all ingestion sources. Ordered by balance date.
It calculates the balance for each date, by iterating from the date the account was last refreshed to the `to` and `from` dates provided. It then checks all the transactions within this range, calculating the balance at the end of each day.
This endpoint limits the date from which it gets balances by the oldest `transaction_window` on the account. If `transaction_windows` are not present, it is not possible to calculate balances and the endpoint returns an empty list.
You can only request balances within transaction windows, therefore if you ingest transactions without a transaction window, you won't be able to request balance for that time range. However those transactions will be used to calculate the balance as well.
For users ingesting data via the `Ingest Accounts` endpoint, you can increase the range and accuracy of the data supplied from this service by including the transaction_window field upon account ingestion.
The balances selected to use as latest pending & latest booked in the calculation are selected according to a provider specific balance type priority list.
Results are limited to up to 5000 balance items across all accounts.
operationId: financial_v3_balances_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/QueryFromBudDate'
- $ref: '#/components/parameters/QueryToBudDate'
- in: query
name: granularity
schema:
type: string
example: daily
description: |
Specifies in what interval the balance over time should be retrieved.
Currently supported values include (but are not necessarily limited to):
- `daily`
- `weekly`
- `biweekly`
- `monthly`
- `quarterly`
- `six_monthly`
- `annually`
Defaults to `weekly`.
- $ref: '#/components/parameters/QueryDateField'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBalancesV3Response'
example:
operation_id: financial_v3_balances_get
data:
- account_id: 705e95fea8312d9a9b227b682033d55f
balances:
- date: '2022-11-15T23:59:59Z'
booked:
amount:
value: '900.00'
currency: GBP
credit_debit_indicator: credit
pending:
amount:
value: '850.00'
currency: GBP
credit_debit_indicator: credit
- date: '2022-11-14T23:59:59Z'
booked:
amount:
value: '950.00'
currency: GBP
credit_debit_indicator: credit
pending:
amount:
value: '900.00'
currency: GBP
credit_debit_indicator: credit
- account_id: 9df0b46c8ab58277abc432fee26067ad
balances:
- date: '2022-11-15T23:59:59Z'
booked:
amount:
value: '500'
currency: JPY
credit_debit_indicator: credit
pending:
amount:
value: '500'
currency: JPY
credit_debit_indicator: credit
metadata:
accounts:
5b271e24-9ea5-4d7e-b5da-64f01d32db22:
balance_count: 2
from: '2022-11-14T23:59:59Z'
to: '2022-11-15T23:59:59Z'
max_balance:
value: '500.00'
currency: JPY
min_balance:
value: '200.00'
currency: GBP
b6e9ea3c-71f9-4572-983a-3e5e85470dad:
balance_count: 1
from: '2022-11-15T23:59:59Z'
to: '2022-11-15T23:59:59Z'
max_balance:
value: '500.12'
currency: GBP
min_balance:
value: '0.00'
currency: GBP
parameters:
from: '2020-12-22T00:00:00Z'
to: '2022-11-15T00:00:00Z'
granularity: daily
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: An unauthenticated request was received.
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: financial_v3_balances_get
code_id: internal_error
message: Internal server error has occurred.
/financial/v3/accounts/{account_id}/balances:
get:
tags:
- Retrieve Financial Data
summary: Retrieve Balances Over Time By Account V3
description: |
List the balances of a specific bank account for a customer across all ingestion sources. Ordered by balance date.
It calculates the balance for each date, by iterating from the date the account was last refreshed to the `to` and `from` dates provided. It then checks all the transactions within this range, calculating the balance at the end of each day.
This endpoint limits the date from which it gets balances by the oldest `transaction_window` on the account. If `transaction_windows` are not present, it is not possible to calculate balances and the endpoint returns an empty list.
You can only request balances within transaction windows, therefore if you ingest transactions without a transaction window, you won't be able to request balance for that time range. However those transactions will be used to calculate the balance as well.
For users ingesting data via the `Ingest Accounts` endpoint, you can increase the range and accuracy of the data supplied from this service by including the transaction_window field upon account ingestion.
The balances selected to use as latest pending & latest booked in the calculation are selected according to a provider specific balance type priority list.
Results are limited to up to 5000 balance items.
operationId: financial_v3_accounts_balances_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/QueryFromBudDate'
- $ref: '#/components/parameters/QueryToBudDate'
- $ref: '#/components/parameters/PathAccountID'
- in: query
name: granularity
schema:
type: string
example: daily
description: |
Specifies in what interval the balance over time should be retrieved.
Currently supported values include (but are not necessarily limited to):
- `daily`
- `weekly`
- `biweekly`
- `monthly`
- `quarterly`
- `six_monthly`
- `annually`
Defaults to `weekly`.
- $ref: '#/components/parameters/QueryDateField'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBalancesForAccountIDV3Response'
example:
operation_id: financial_v3_accounts_balances_get
data:
- date: '2022-11-15T23:59:59Z'
booked:
amount:
value: '900.00'
currency: GBP
credit_debit_indicator: credit
pending:
amount:
value: '850.00'
currency: GBP
credit_debit_indicator: credit
- date: '2022-11-14T23:59:59Z'
booked:
amount:
value: '950.00'
currency: GBP
credit_debit_indicator: credit
pending:
amount:
value: '900.00'
currency: GBP
credit_debit_indicator: credit
metadata:
accounts:
balance_count: 2
from: '2022-11-14T23:59:59Z'
to: '2022-11-15T23:59:59Z'
max_balance:
value: '500.12'
currency: GBP
min_balance:
value: '0.00'
currency: GBP
parameters:
from: '2020-12-22T00:00:00Z'
to: '2022-11-15T00:00:00Z'
granularity: daily
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: An unauthenticated request was received.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestNotFoundResponse'
example:
operation_id: financial_v3_accounts_balances_get
code_id: account_not_found
message: The specified account could not be found. Please check the account identifier is correct. The account might be closed or suspended.
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: financial_v3_accounts_balances_get
code_id: internal_error
message: Internal server error has occurred.
/financial/v2/transactions:
get:
tags:
- Retrieve Financial Data
summary: Retrieve Transactions V2
description: |
List the Transactions for a customer across all ingestion sources and accounts. Ordered by `date_time` and then `transaction_id` descending.
They are also provided with Enrichments - contextual information generated by Bud's artificial intelligence models. Enrichments are optional because not all Enrichments are relevant to all Transactions, or because they did not have enough information to generate enrichments (e.g. pending Transactions).
The Enrichment process also generates tags, which can be used for filtering using the `include_tags` and `exclude_tags` query parameters.
operationId: v2_transactions_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- in: query
name: date_from
schema:
type: string
example: '2022-05-28T00:00:00Z'
description: |
Date (RFC3339) from which the transactions should be returned from. To maintain backwards compatibility, dates in the format (YYYY-MM-DD) can also be used and will be assumed to be UTC.
- in: query
name: date_to
schema:
type: string
example: '2022-05-29T00:00:00Z'
description: |
Date (RFC3339) from which the transactions should be returned to. To maintain backwards compatibility, dates in the format (YYYY-MM-DD) can also be used and will be assumed to be UTC. Uses the current date by default.
- in: query
name: page_size
schema:
type: integer
example: 100
description: |
Maximum number of results to be returned. Defaults to 100, maximum is 200.
Note: When using the `exclude_tags` filter, the response may contain more transactions than the specified `page_size` to ensure complete filtering. Always use the presence of `next_page_token` to determine if additional pages are available.
- in: query
name: page_token
schema:
type: string
example: eyJvZmZzZXQiOjEwMH0
description: The token required to fetch a specific page of results. Provided by the `next_page_token` field in the previous request.
- in: query
name: account_id
schema:
type: string
example: 5bd9ecaf31fc2d5172fd89cb61b89fc6
description: Identifier of the accounts from which transactions should be returned.
- in: query
name: merchant
schema:
type: string
description: Human readable identifier of the merchants for which associated transactions should be returned.
example: netflix
- in: query
name: category_l1
schema:
type: string
example: bills
description: Identifier of the Category Level 1 for which associated transactions should be returned.
- in: query
name: category_l2
schema:
type: string
example: tv_and_broadband
description: Identifier of the Category Level 2 for which associated transactions should be returned.
- in: query
name: include_tags
schema:
type: array
items:
type: string
example:
- regular-transaction
description: Tags for which associated transactions should be returned. See response body example for an exhaustive list of possible tags.
- in: query
name: exclude_tags
schema:
type: array
items:
type: string
example:
- benefit
description: |
Tags for which associated transactions should not be returned. See response body example for an exhaustive list of possible tags.
When this filter is applied, the response may include more transactions than the `page_size` to ensure accurate filtering. Always use the presence of `next_page_token` to determine if additional pages are available.
- in: query
name: credit_debit_indicator
schema:
type: string
enum:
- credit
- debit
example: credit
description: Credit debit indicator for which associated transactions should be returned.
- in: query
name: updated_after
schema:
type: string
example: '2024-06-01T11:00:00Z'
description: |
The `updated_after` parameter lets you retrieve transactions that have been modified since a specific date and time. This format should follow the RFC3339 standard (e.g., "2024-06-01T11:00:00Z").
This parameter is particularly useful for keeping local copies of transactions up-to-date. By storing the timestamp of your last successful fetch, you can request only transactions updated after that point during subsequent retrievals.
This approach ensures you only fetch the latest changes, making the process more streamlined.
- in: query
name: status
schema:
type: string
enum:
- booked
- pending
- declined
example: booked
description: |
Statuses of transactions to be returned. This parameter can be supplied multiple times to fetch transactions with a combination of statuses.
By default, declined transactions are excluded from the results.
Note: Transactions ingested via Open Banking will only come as `booked` or `pending`.
The `declined` status is only applicable to transactions ingested through our `Ingest First Party Data` endpoint.
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ListTransactionsResponse'
examples:
Multiple Transactions:
value:
operation_id: v2_transactions_get
data:
- transaction_id: fbdc28e82f0f137586a526a88ec4a6be
account_id: 5bd9ecaf31fc2d5172fd89cb61b89fc6
provider: BankOfBud
description: tesco store 2613 on 28 may visa
credit_debit_indicator: debit
status: booked
suggested_description: Tesco
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v2/tesco.jpeg
transaction_type:
bud_code: DEB
description: Debit card transaction
amount:
value: '20.25'
currency: GBP
date_time: '2022-05-28T15:00:00Z'
value_date_time: '2022-05-29T00:00:00Z'
merchant_category_code: '5411'
enrichments:
categories:
l1:
slug: food_and_drink
confidence: '0.99'
l2:
slug: groceries
confidence: '0.99'
merchant:
id: 17ac2742-8c93-4c11-a01f-17ad65b950ce
slug: tesco
display_name: Tesco
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v1/tesco.jpeg
website: www.tesco.com
tokens:
- value: tesco store
confidence: '1.00'
processor:
id: bd7125f7-1a1e-4aeb-a774-80f86ec989cc
slug: visa
display_name: Visa
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/bd7125f7-1a1e-4aeb-a774-80f86ec989cc/v1/visa.jpeg
website: https://www.paypal.com
tokens:
- value: visa
confidence: '1.00'
location:
address:
address_lines:
- 180 Shepherd's Bush Road
- London
- Greater London
- W6 7NL
street_address: 180 Shepherd's Bush Road
city: London
region: Greater London
postal_code: W6 7NL
country: GB
geolocation:
longitude: 51.497369
latitude: -0.224128
transaction_types:
- card
- debit
- transaction_id: a2294cebb45d2a6e0cfc70d270988d8c
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: caffe nero 495 ladbroke london gbr
credit_debit_indicator: debit
status: booked
suggested_description: Caffè Nero
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v2/caffnero.jpeg
transaction_type:
bud_code: DEB
description: Debit card transaction
amount:
value: '3.29'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
value_date_time: '2022-05-27T00:00:00Z'
merchant_category_code: '5814'
enrichments:
categories:
l1:
slug: food_and_drink
confidence: '0.99'
l2:
slug: coffee
confidence: '0.99'
merchant:
id: 4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf
slug: caffnero
display_name: Caffè Nero
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v1/caffnero.jpeg
website: www.caffenero.com/uk
tokens:
- value: caffe nero
confidence: '1.00'
location:
address:
address_lines:
- 120-122 Ladbroke Grove
- London
- Greater London
- W10 5NE
street_address: 120-122 Ladbroke Grove
city: London
region: Greater London
postal_code: W10 5NE
country: GB
geolocation:
longitude: 51.517301
latitude: -0.209689
tokens:
- gbr
- ladbroke
- london
- transaction_id: cfb6dd1f4c73e1fc36aac756e12644d7
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: JOHN SMITH RENT SHARE
credit_debit_indicator: debit
status: booked
suggested_description: JOHN SMITH RENT SHARE
transaction_type:
bud_code: BAT
description: Bank Transfer
amount:
value: '375.00'
currency: GBP
date_time: '2022-05-30T00:00:00Z'
value_date_time: '2022-05-30T00:00:00Z'
enrichments:
categories:
l1:
slug: mortgage_and_rent
confidence: '0.98'
l2:
slug: rent
confidence: '0.98'
regularity:
frequency: monthly
predicted_date_times:
- '2022-06-30T00:00:00Z'
- '2022-08-01T00:00:00Z'
- '2022-08-30T00:00:00Z'
group_label: 982cb10a156f53a082840ba72c3ee3291b95379a5c39a9d5972fd50731b169e3
names:
- john smith
tags:
- regular-transaction
metadata:
results: 2
next_page_token: eyJvZmZzZXQiOjEwMH0
Updated After Response:
value:
operation_id: v2_transactions_get
data:
- transaction_id: fbdc28e82f0f137586a526a88ec4a6be
account_id: 5bd9ecaf31fc2d5172fd89cb61b89fc6
provider: BankOfBud
description: tesco store 2613 on 28 may visa
credit_debit_indicator: debit
status: booked
suggested_description: Tesco
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v2/tesco.jpeg
transaction_type:
bud_code: DEB
description: Debit card transaction
amount:
value: '20.25'
currency: GBP
date_time: '2022-05-28T15:00:00Z'
value_date_time: '2022-05-29T00:00:00Z'
merchant_category_code: '5411'
enrichments:
categories:
l1:
slug: food_and_drink
confidence: '0.99'
l2:
slug: groceries
confidence: '0.99'
merchant:
id: 17ac2742-8c93-4c11-a01f-17ad65b950ce
slug: tesco
display_name: Tesco
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v1/tesco.jpeg
website: www.tesco.com
tokens:
- value: tesco store
confidence: '1.00'
processor:
id: bd7125f7-1a1e-4aeb-a774-80f86ec989cc
slug: visa
display_name: Visa
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/bd7125f7-1a1e-4aeb-a774-80f86ec989cc/v1/visa.jpeg
website: https://www.paypal.com
tokens:
- value: visa
confidence: '1.00'
location:
address:
address_lines:
- 180 Shepherd's Bush Road
- London
- Greater London
- W6 7NL
street_address: 180 Shepherd's Bush Road
city: London
region: Greater London
postal_code: W6 7NL
country: GB
geolocation:
longitude: 51.497369
latitude: -0.224128
transaction_types:
- card
- debit
- transaction_id: a2294cebb45d2a6e0cfc70d270988d8c
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: caffe nero 495 ladbroke london gbr
credit_debit_indicator: debit
status: booked
suggested_description: Caffè Nero
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v2/caffnero.jpeg
transaction_type:
bud_code: DEB
description: Debit card transaction
amount:
value: '3.29'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
value_date_time: '2022-05-27T00:00:00Z'
merchant_category_code: '5814'
enrichments:
categories:
l1:
slug: food_and_drink
confidence: '0.99'
l2:
slug: coffee
confidence: '0.99'
merchant:
id: 4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf
slug: caffnero
display_name: Caffè Nero
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/4d7a77bd-29a1-4b6a-b0b4-04389b5b36bf/v1/caffnero.jpeg
website: www.caffenero.com/uk
tokens:
- value: caffe nero
confidence: '1.00'
location:
address:
address_lines:
- 120-122 Ladbroke Grove
- London
- Greater London
- W10 5NE
street_address: 120-122 Ladbroke Grove
city: London
region: Greater London
postal_code: W10 5NE
country: GB
geolocation:
longitude: 51.517301
latitude: -0.209689
tokens:
- gbr
- ladbroke
- london
- transaction_id: cfb6dd1f4c73e1fc36aac756e12644d7
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: JOHN SMITH RENT SHARE
credit_debit_indicator: debit
status: booked
suggested_description: JOHN SMITH RENT SHARE
transaction_type:
bud_code: BAT
description: Bank Transfer
amount:
value: '375.00'
currency: GBP
date_time: '2022-05-30T00:00:00Z'
value_date_time: '2022-05-30T00:00:00Z'
enrichments:
categories:
l1:
slug: mortgage_and_rent
confidence: '0.98'
l2:
slug: rent
confidence: '0.98'
regularity:
frequency: monthly
predicted_date_times:
- '2022-06-30T00:00:00Z'
- '2022-08-01T00:00:00Z'
- '2022-08-30T00:00:00Z'
group_label: 982cb10a156f53a082840ba72c3ee3291b95379a5c39a9d5972fd50731b169e3
names:
- john smith
tags:
- regular-transaction
metadata:
results: 2
updated_after: '2022-05-29T00:00:00Z'
deleted:
- transaction_id: a8f6d57f-a95e-4925-9775-4c4d85911f4c
at: '2022-06-01T12:59:00Z'
- transaction_id: 4354e288-2f67-43d6-a1de-d6750e0d5f73
at: '2022-06-02T13:12:00Z'
next_page_token: eyJvZmZzZXQiOjEwMH0
Single Transaction Without Enrichments:
value:
operation_id: v2_transactions_get
data:
- transaction_id: da4ad499c86956e65e811fc88f6b54af
account_id: 72fa858459bd32ce0b5fd9daf813fd07
provider: BankOfBud
description: a
credit_debit_indicator: credit
status: pending
suggested_description: a
amount:
value: '10.99'
currency: GBP
date_time: '2022-01-02T15:00:00Z'
value_date_time: '2022-01-02T15:00:00Z'
metadata:
results: 1
next_page_token: eyJvZmZzZXQiOjEwMH0
No Transactions:
value:
operation_id: v2_transactions_get
data: []
metadata:
results: 0
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/financial/v2/authorised-payments:
get:
tags:
- Retrieve Financial Data
summary: Retrieve Authorised Payments V2
description: |
Retrieves a list of a customer's authorised payments. Currently supported authorised payment types include (but are not necessarily limited to): - direct debits - standing orders - scheduled payments
> 📘 Note: > > Not all providers support authorised payments
operationId: financial_v2_authorised_payments_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- in: query
name: account_id
schema:
type: string
description: |
Identifier of the accounts from which transactions should be returned.
Example: "5bd9ecaf31fc2d5172fd89cb61b89fc6"
- in: query
name: page_size
schema:
type: integer
example: 100
description: |
Maximum number of results to be returned. Defaults to 100, maximum is 200.
Example: 100
- in: query
name: page_token
schema:
type: string
example: eyJvZmZzZXQiOjEwMH0
description: |
The token required to fetch a specific page of results. Provided by the `next_page_token` field in the previous request. Example: `eyJvZmZzZXQiOjEwMH0`
- in: query
name: status
schema:
type: string
example: active
description: |
Use this parameter to filter the results returned on the `status` associated with each result. If this parameter is not provided then results of any `status` will be returned.
Currently supported values include (but are not necessarily limited to):
- `active``
- `inactive`
- `cancelled`
- `expired`
- `suspended`
- `unknown`
- in: query
name: type
schema:
type: string
example: direct_debit
description: |
Use this parameter to filter the results returned on the `type` associated with each result. If this parameter is not provided then results of any `type` will be returned.
Currently supported values include (but are not necessarily limited to):
- `direct_debit`
- `standing_order`
- `scheduled_payment`
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetAuthorisedPaymentsV2Response'
examples:
Direct debit example:
value:
operation_id: financial_v2_authorised_payments_get
data:
- account_id: RxsYshVGded4JeilkXgWKdXA
id: DD03
type: direct_debit
reference: TV streaming subscription
status: active
name: Television streaming subscription
frequency: monthly
details:
- credit_debit_indicator: debit
amount:
value: '7.89'
currency: GBP
date: '2017-04-05T10:43:07+00:00'
type: previous_payment
metadata:
results: 1
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
CustomerID Not Sent:
value:
operation_id: financial_v2_authorised_payments_get
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id: not present
CustomerID and CustomerSecret Not Sent:
value:
operation_id: financial_v2_authorised_payments_get
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id:
- not present
X-Customer-Secret:
- not present
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request.
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8.'
/financial/v2/accounts:
get:
deprecated: true
tags:
- Retrieve Financial Data
summary: Retrieve Accounts V2
description: |
Retrieves a list of a customer's connected accounts. The result can be filtered using the parameters outlined below.
> ❗️ Deprecation:
>
> Support will cease for this endpoint on the 1st of April 2025 - please complete your migration to the Retrieve Accounts V3 endpoint by that point in time. For further details, contact your Bud account manager or email help@thisisbud.com.
operationId: financial_v2_accounts
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/QueryCurrency'
- $ref: '#/components/parameters/QueryProvider'
- in: query
name: account_type
schema:
type: string
example: current_account
description: |
Use this parameter to filter the results returned on the `account_type` associated with each result. Multiple values are accepted. If this parameter is not provided then results of any `account_type` will be returned.
Currently supported values include (but are not necessarily limited to):
- `charge_card`
- `credit_card`
- `current_account`
- `e_money`
- `investment`
- `loan`
- `mortgage`
- `other`
- `pre_paid_card`
- `savings`
- in: query
name: usage_type
schema:
type: string
example: personal
description: |
Use this parameter to filter the results returned on the `usage_type` associated with each result. Multiple values are accepted. If this parameter is not provided then results of any `usage_type` will be returned.
Currently supported values include (but are not necessarily limited to):
- `personal`
- `business`
- in: query
name: holder_relationship_type
schema:
type: string
example: joint
description: |
Use this parameter to filter the results returned on the `holder_relationship_type` associated with each result. Multiple values are accepted. If this parameter is not provided then results of any `holder_relationship_type` will be returned.
Currently supported values include (but are not necessarily limited to):
- `sole`
- `joint`
- `delegate`
- `unknown`
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAccountsV2Response'
examples:
Account Without Parties Data:
value:
operation_id: financial_v2_accounts
data:
- account_id: RxsYshVGded4JeilkXgWKdXA
currency: GBP
holder:
name: David Smith
relationship: unknown
account_name: My Current Account
account_type: current_account
usage_type: personal
provider: BankOfBud
identifiers:
uk_sort_code: '126432'
uk_account_number: '31510604'
balances:
- date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
- date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: expected
credit_debit_indicator: credit
credit_lines:
- date: '2023-01-12T00:00:00Z'
type: credit
amount:
value: '1000.00'
currency: GBP
metadata:
parameters:
currencies:
- GBP
result_count: 1
Account With Parties Data:
value:
operation_id: financial_v2_accounts
data:
- account_id: RxsYshVGded4JeilkXgWKdXA
currency: GBP
holders:
- name: David Smith
relationship: joint
- name: Jane Smith
relationship: joint
account_name: Household Account
account_type: current_account
usage_type: personal
provider: BankOfBud
identifiers:
uk_sort_code: '124332'
uk_account_number: '12642318'
balances:
- date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
- date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: expected
credit_debit_indicator: credit
credit_lines:
- date: '2023-01-12T00:00:00Z'
type: credit
amount:
value: '1000.00'
currency: GBP
metadata:
parameters:
currencies:
- GBP
result_count: 1
Closed Account:
value:
operation_id: financial_v2_accounts
data:
- account_id: RxsYshVGded4JeilkXgWKdXA
currency: GBP
holders:
- name: David Smith
relationship: joint
- name: Jane Smith
relationship: joint
account_name: Household Account
account_type: current_account
usage_type: personal
status: closed
closed_at: '2023-01-13T00:00:00Z'
provider: BankOfBud
identifiers:
uk_sort_code: '124332'
uk_account_number: '12642318'
balances:
- date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
- date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: expected
credit_debit_indicator: credit
credit_lines:
- date: '2023-01-12T00:00:00Z'
type: credit
amount:
value: '1000.00'
currency: GBP
metadata:
parameters:
currencies:
- GBP
result_count: 1
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
CustomerID Not Sent:
value:
operation_id: financial_v2_accounts
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id: not present
CustomerID and CustomerSecret Not Sent:
value:
operation_id: financial_v2_accounts
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id:
- not present
X-Customer-Secret:
- not present
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/financial/v2/accounts/{account_id}:
get:
deprecated: true
tags:
- Retrieve Financial Data
summary: Retrieve Account By ID V2
description: |
Retrieves a customer's connected account by its ID.
> ❗️ Deprecation:
>
> Support will cease for this endpoint on the 1st of April 2025 - please complete your migration to the Retrieve Accounts V3 endpoint by that point in time. For further details, contact your Bud account manager or email help@thisisbud.com.
operationId: financial_v2_accounts_account_id
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/PathAccountID'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveAccountByIDV2Response'
examples:
Single Holder Personal Account:
value:
operation_id: financial_v2_accounts_account_id
data:
account_id: RxsYshVGded4JeilkXgWKdXA
currency: GBP
holder:
name: David Smith
relationship: unknown
account_name: My Current Account
account_type: current_account
provider: BankOfBud
identifiers:
uk_sort_code: '126432'
uk_account_number: '31510604'
balance:
date: '2023-01-12T00:00:00Z'
booked:
amount:
value: '3552.61'
currency: GBP
credit_debit_indicator: debit
credit_limit:
value: '1000.00'
currency: GBP
metadata:
parameters:
currencies:
- GBP
result_count: 1
Multiple Holder Joint Account:
value:
operation_id: financial_v2_accounts_account_id
data:
account_id: RxsYshVGded4JeilkXgWKdXA
currency: GBP
holders:
- name: David Smith
relationship: joint
- name: Jane Smith
relationship: joint
account_name: Household Account
account_type: current_account
provider: BankOfBud
identifiers:
uk_sort_code: '124332'
uk_account_number: '12642318'
balances:
- date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
- date: '2023-01-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: expected
credit_debit_indicator: credit
credit_lines:
- date: '2023-01-12T00:00:00Z'
type: credit
amount:
value: '1000.00'
currency: GBP
metadata:
parameters:
currencies:
- GBP
result_count: 1
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
CustomerID Not Sent:
value:
operation_id: financial_v2_accounts_account_id
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id: not present
CustomerID and CustomerSecret Not Sent:
value:
operation_id: financial_v2_accounts_account_id
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id:
- not present
X-Customer-Secret:
- not present
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
delete:
tags:
- Manage Financial Data
summary: Remove Account Data V2
description: |
Delete all data (including transactions and balances) related to the specified account.
operationId: v2_account_delete
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- in: path
name: account_id
required: true
schema:
type: string
description: The unique identifier of the account to be deleted.
responses:
'204':
description: |
No Content - The account data has been successfully deleted.
Note: This response is also given if the account did not exist.
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
CustomerID Not Sent:
value:
operation_id: v2_account_delete
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id: not present
CustomerID and CustomerSecret Not Sent:
value:
operation_id: v2_account_delete
code_id: failed_validation
message: Invalid request payload.
errors:
X-Customer-Id:
- not present
X-Customer-Secret:
- not present
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/financial/v2/balances:
get:
tags:
- Retrieve Financial Data
summary: Retrieve Balances Over Time
description: |
> ❗️ Deprecation:
>
> Support will cease for this endpoint on the 1st of April 2025 - please complete your migration to the Retrieve Balances Over Time V3 endpoint by that point in time. For further details, contact your Bud account manager or email help@thisisbud.com.
List the balances of each bank account for a customer across all ingestion sources. Ordered by balance date.
It calculates the balance for each date, by iterating from the date the account was last refreshed to the `to`
and `from` dates provided. It then checks all the transactions within this range, calculating the balance at
the end of each day.
This endpoint limits the date from which it gets balances by the oldest `transaction_window` on the
account. If `transaction_windows` are not present, it is not possible to calculate balances and the endpoint
returns an empty list.
You can only request balances within transaction windows, therefore if you ingest transactions without a
transaction window, you won't be able to request balance for that time range. However those transactions will be
used to calculate the balance as well.
For users ingesting data via the `Ingest Accounts` endpoint, you can increase the range and accuracy of the
data supplied from this service by including the transaction_window field upon account ingestion.
Results are limited to up to 5000 balance items across all accounts.
operationId: financial_v2_balances_get
deprecated: true
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/QueryFromBudDate'
- $ref: '#/components/parameters/QueryToBudDate'
- in: query
name: granularity
schema:
type: string
example: daily
description: |
Specifies in what interval the balance over time should be retrieved.
Currently supported values include (but are not necessarily limited to):
- `daily`
- `weekly`
- `biweekly`
- `monthly`
- `quarterly`
- `six_monthly`
- `annually`
Defaults to `weekly`.
- $ref: '#/components/parameters/QueryDateField'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBalancesResponse'
example:
operation_id: financial_v2_balances_get
data:
- account_id: 705e95fea8312d9a9b227b682033d55f
balances:
- date: '2022-11-15T23:59:59Z'
booked:
amount:
value: '900.00'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
pending:
amount:
value: '850.00'
currency: GBP
type: expected
credit_debit_indicator: credit
- date: '2022-11-14T23:59:59Z'
booked:
amount:
value: '950.00'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
pending:
amount:
value: '900.00'
currency: GBP
type: expected
credit_debit_indicator: credit
- account_id: 9df0b46c8ab58277abc432fee26067ad
balances:
- date: '2022-11-15T23:59:59Z'
booked:
amount:
value: '500'
currency: JPY
type: interim_booked
credit_debit_indicator: credit
metadata:
accounts:
5b271e24-9ea5-4d7e-b5da-64f01d32db22:
balance_count: 2
from: '2022-11-14T23:59:59Z'
to: '2022-11-15T23:59:59Z'
max_balance:
value: '500.00'
currency: JPY
min_balance:
value: '200.00'
currency: GBP
b6e9ea3c-71f9-4572-983a-3e5e85470dad:
balance_count: 1
from: '2022-11-15T23:59:59Z'
to: '2022-11-15T23:59:59Z'
max_balance:
value: '500.12'
currency: GBP
min_balance:
value: '0.00'
currency: GBP
parameters:
from: '2020-12-22T00:00:00Z'
to: '2022-11-15T00:00:00Z'
granularity: daily
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: An unauthenticated request was received.
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: financial_v2_balances_get
code_id: internal_error
message: Internal server error has occurred.
/financial/v2/accounts/{account_id}/balances:
get:
tags:
- Retrieve Financial Data
summary: Retrieve Balances Over Time By Account
description: |
> ❗️ Deprecation:
>
> Support will cease for this endpoint on the 1st of April 2025 - please complete your migration to the Retrieve Balances Over Time By Account V3 endpoint by that point in time. For further details, contact your Bud account manager or email help@thisisbud.com.
List the balances of a specific bank account for a customer across all ingestion sources. Ordered by balance
date.
It calculates the balance for each date, by iterating from the date the account was last refreshed to the `to`
and `from` dates provided. It then checks all the transactions within this range, calculating the balance at
the end of each day.
This endpoint limits the date from which it gets balances by the oldest `transaction_window` on the
account. If `transaction_windows` are not present, it is not possible to calculate balances and the endpoint
returns an empty list.
You can only request balances within transaction windows, therefore if you ingest transactions without a
transaction window, you won't be able to request balance for that time range. However those transactions will be
used to calculate the balance as well.
For users ingesting data via the `Ingest Accounts` endpoint, you can increase the range and accuracy of the
data supplied from this service by including the transaction_window field upon account ingestion.
Results are limited to up to 5000 balance items.
operationId: financial_v2_accounts_balances_get
deprecated: true
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/QueryFromBudDate'
- $ref: '#/components/parameters/QueryToBudDate'
- $ref: '#/components/parameters/PathAccountID'
- in: query
name: granularity
schema:
type: string
example: daily
description: |
Specifies in what interval the balance over time should be retrieved.
Currently supported values include (but are not necessarily limited to):
- `daily`
- `weekly`
- `biweekly`
- `monthly`
- `quarterly`
- `six_monthly`
- `annually`
Defaults to `weekly`.
- $ref: '#/components/parameters/QueryDateField'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBalancesForAccountIDResponse'
example:
operation_id: financial_v2_accounts_balances_get
data:
- date: '2022-11-15T23:59:59Z'
booked:
amount:
value: '900.00'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
pending:
amount:
value: '850.00'
currency: GBP
type: expected
credit_debit_indicator: credit
- date: '2022-11-14T23:59:59Z'
booked:
amount:
value: '950.00'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
pending:
amount:
value: '900.00'
currency: GBP
type: expected
credit_debit_indicator: credit
metadata:
accounts:
balance_count: 2
from: '2022-11-14T23:59:59Z'
to: '2022-11-15T23:59:59Z'
max_balance:
value: '500.12'
currency: GBP
min_balance:
value: '0.00'
currency: GBP
parameters:
from: '2020-12-22T00:00:00Z'
to: '2022-11-15T00:00:00Z'
granularity: daily
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: An unauthenticated request was received.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestNotFoundResponse'
example:
operation_id: financial_v2_accounts_balances_get
code_id: account_not_found
message: The specified account could not be found. Please check the account identifier is correct. The account might be closed or suspended.
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: financial_v2_accounts_balances_get
code_id: internal_error
message: Internal server error has occurred.
/v1/provider/{provider}:
delete:
tags:
- Manage Financial Data
summary: Remove Provider Data
description: |
Delete all data (transactions, enrichments, accounts) related to the specified provider.
operationId: v1_provider_delete
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/OBProvider'
responses:
'204':
description: The request was successfully processed.
'400':
description: Bad request.
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/corrections/v2/categories:
post:
tags:
- Correct Financial Data
summary: Correct Transaction Categories V2
description: |
Allow a customer to change a transaction’s (and similar transactions') category and/or subcategory.
If `include_similar` is set to `true`, then all previous and future transactions (i.e. those that are yet to happen yet) that are similar in nature to the specified transaction id will be corrected with the provided category and/or subcategory.
Similar transactions are determined based on transactions with similar descriptions & amounts.
operationId: corrections_v2_categories_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerCategoryCorrectionRequest'
example:
- transaction_id: 7affc586-5600-4434-ac5f-1a845260d7d9
category_l1: food_and_drink
category_l2: coffee
include_similar: false
responses:
'200':
description: The request was successfully processed
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerCategoryCorrectionResponse'
example:
operation_id: corrections_v2_categories_post
data:
- transaction_id: 7affc586-5600-4434-ac5f-1a845260d7d9
category_l1: food_and_drink
category_l2: coffee
include_similar: false
metadata:
results: 1
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: corrections_v2_categories_post
code_id: validation_error
message: Bad request payload
errors:
X-Client-ID: This value should not be blank
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/corrections/v2/merchants:
post:
tags:
- Correct Financial Data
summary: Correct Transaction Merchant
description: |
Allow a customer to change a transaction’s (and similar transactions') merchant.
If `include_similar` is set to `true`, then all previous and future transactions (i.e. those that are yet to happen yet) that are similar in nature to the specified transaction id will be corrected with the provided merchant.
Similar transactions are determined based on transactions with similar descriptions & amounts.
operationId: corrections_v2_merchants_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerMerchantCorrectionRequest'
examples:
Single Transaction Correction:
value:
- transactions:
- 7affc586-5600-4434-ac5f-1a845260d7d9
merchant_id: f2b21ff7-836d-468c-8928-e81060d49988
include_similar: false
Similar Transactions Correction:
value:
- transactions:
- 7affc586-5600-4434-ac5f-1a845260d7d9
merchant_id: f2b21ff7-836d-468c-8928-e81060d49988
include_similar: true
Remove Merchant From Single Transaction:
value:
- transactions:
- 7affc586-5600-4434-ac5f-1a845260d7d9
merchant_id: ''
include_similar: false
responses:
'200':
description: The request was successfully processed
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerMerchantCorrectionResponse'
examples:
Single Transaction Correction:
value:
operation_id: corrections_v2_merchants_post
data:
- transaction_id: 7affc586-5600-4434-ac5f-1a845260d7d9
account_id: 5bd9ecaf31fc2d5172fd89cb61b89fc6
provider: BankOfBud
description: paypal* specialty coffee
credit_debit_indicator: debit
status: booked
suggested_description: Pact Coffee
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/9f967c91-7cf5-46a4-bc0b-92541a4ea7da/v1/pactcoffee.jpeg
amount:
value: '10.99'
currency: GBP
date_time: '2022-05-28T10:00:00Z'
value_date_time: '2022-05-29T00:00:00Z'
merchant_category_code: '5814'
enrichments:
categories:
l1:
slug: eating_out
confidence: '0.99'
l2:
slug: cafes_and_eating_out
confidence: '0.98'
merchant:
id: 9f967c91-7cf5-46a4-bc0b-92541a4ea7da
slug: pactcoffee
display_name: Pact Coffee
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/9f967c91-7cf5-46a4-bc0b-92541a4ea7da/v1/pactcoffee.jpeg
website: https://www.pactcoffee.com
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
processor:
id: 18f63293-0217-4520-bbf0-071dca7a9d04
slug: paypal
display_name: PayPal
logo: http://url/paypal_logo.jpeg
tokens:
- value: paypal
confidence: '0.92'
website: https://www.paypal.com
regularity:
frequency: monthly
predicted_date_times:
- '2022-06-28T15:00:00Z'
- '2022-07-28T15:00:00Z'
- '2022-08-28T15:00:00Z'
group_label: a_group_id
transaction_types:
- card
- debit
names:
- jane doe
tags:
- regular-transaction
metadata:
effected_transactions_count: 1
include_similar: false
merchant_id: 9f967c91-7cf5-46a4-bc0b-92541a4ea7da
transactions:
- 7affc586-5600-4434-ac5f-1a845260d7d9
Single Transaction Correction Include Similar:
value:
operation_id: corrections_v2_merchants_post
data:
- transaction_id: 7affc586-5600-4434-ac5f-1a845260d7d9
account_id: 5bd9ecaf31fc2d5172fd89cb61b89fc6
provider: BankOfBud
description: paypal* specialty coffee
credit_debit_indicator: debit
status: booked
suggested_description: Pact Coffee
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/9f967c91-7cf5-46a4-bc0b-92541a4ea7da/v1/pactcoffee.jpeg
amount:
value: '10.99'
currency: GBP
date_time: '2022-05-28T10:00:00Z'
value_date_time: '2022-05-29T00:00:00Z'
merchant_category_code: '5814'
enrichments:
categories:
l1:
slug: eating_out
confidence: '0.99'
l2:
slug: cafes_and_eating_out
confidence: '0.98'
merchant:
id: 9f967c91-7cf5-46a4-bc0b-92541a4ea7da
slug: pactcoffee
display_name: Pact Coffee
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/9f967c91-7cf5-46a4-bc0b-92541a4ea7da/v1/pactcoffee.jpeg
website: https://www.pactcoffee.com
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
processor:
id: 18f63293-0217-4520-bbf0-071dca7a9d04
slug: paypal
display_name: PayPal
logo: http://url/paypal_logo.jpeg
tokens:
- value: paypal
confidence: '0.92'
website: https://www.paypal.com
regularity:
frequency: monthly
predicted_date_times:
- '2022-06-28T15:00:00Z'
- '2022-07-28T15:00:00Z'
- '2022-08-28T15:00:00Z'
group_label: a_group_id
transaction_types:
- card
- debit
names:
- jane doe
tags:
- regular-transaction
- transaction_id: similar_transaction_id
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: specialty coffee
credit_debit_indicator: debit
status: booked
suggested_description: specialty coffee
amount:
value: '50.23'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
value_date_time: '2022-05-27T00:00:00Z'
merchant_category_code: '5411'
enrichments:
categories:
l1:
slug: eating_out
confidence: '0.99'
l2:
slug: cafes_and_eating_out
confidence: '0.98'
merchant:
id: 9f967c91-7cf5-46a4-bc0b-92541a4ea7da
slug: pactcoffee
display_name: Pact Coffee
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/9f967c91-7cf5-46a4-bc0b-92541a4ea7da/v1/pactcoffee.jpeg
website: https://www.pactcoffee.com
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
transaction_types:
- card
- debit
metadata:
effected_transactions_count: 2
include_similar: true
merchant_id: 9f967c91-7cf5-46a4-bc0b-92541a4ea7da
transactions:
- 7affc586-5600-4434-ac5f-1a845260d7d9
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Invalid Merchant:
summary: merchant_id doesn't match a known merchant
value:
operation_id: corrections_v2_merchants_post
code_id: failed_validation
message: invalid merchant in request
errors:
body.merchant_id: invalid merchant id
Invalid Transaction:
summary: 1 or more transaction ids are invalid
value:
operation_id: corrections_v2_merchants_post
code_id: failed_validation
message: invalid transaction in request
errors: null
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/corrections/v2/merchants/search/{merchant_query}:
get:
tags:
- Correct Financial Data
summary: Correction Merchant Search
description: |
Allows a customer to find a merchant to be used for a correction.
operationId: corrections_v2_merchant_search_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/MerchantCorrectionSearchQuery'
responses:
'200':
description: The request was successfully processed
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerMerchantCorrectionSearchResponse'
example:
operation_id: corrections_v2_merchant_search_get
data:
- id: f2b21ff7-836d-468c-8928-e81060d49988
display_name: Apple
slug: apple
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/f2b21ff7-836d-468c-8928-e81060d49988/v1/apple.jpeg
website: https://www.apple.com
- id: a3240c82-728d-4d63-b1b8-9569cae844e8
display_name: Tappily
slug: tappily
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/a3240c82-728d-4d63-b1b8-9569cae844e8/v1/tappily.jpeg
website: https://www.tappily.co.uk
- id: bbf422fd-0db3-4988-a037-36476f6bd774
display_name: Zapp
slug: zapp
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/bbf422fd-0db3-4988-a037-36476f6bd774/v1/zapp.jpeg
website: https://tryzapp.com
- id: b97244e4-c1bf-4c70-a529-e250fc5baf39
display_name: WAPPA LTD
slug: wappaltd
logo: https://assets.thisisbud.com/bud-datasci-images/merchant_logo_placeholder.png
- id: 2270343a-110d-4554-8871-33f2e18f8311
display_name: Apple Pay
slug: applepay
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/2270343a-110d-4554-8871-33f2e18f8311/v2/applepay.jpeg
website: https://www.apple.com
metadata:
query: appl
results: 5
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Invalid Query Size:
summary: query size to small
value:
operation_id: corrections_v2_merchant_search_get
code_id: failed_validation
message: invalid search query size
errors: null
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
'429':
description: An unexpected HTTP method was used
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Too Many Requests:
summary: making too many requests to endpoint
value:
operation_id: unknown
code_id: unknown
message: Too many requests
errors: null
5XX:
description: An unexpected error occurred on the server side
/corrections/v2/custom-merchants:
post:
tags:
- Correct Financial Data
summary: Create a new custom merchant
description: |
Creates a new custom merchant for use in the merchant corrections flow.
operationId: corrections_v2_custom_merchants_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomMerchantRequest'
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- corrections_v2_custom_merchants_post
data:
type: object
required:
- custom_merchant_id
properties:
custom_merchant_id:
type: string
format: uuid
example:
operation_id: corrections_v2_custom_merchants_post
data:
custom_merchant_id: 43730d83-479b-4125-8853-0276fa8c45a1
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: corrections_v2_custom_merchants_post
code_id: failed_validation
message: validation failed
errors:
validation_errors:
- name cannot be empty
5XX:
description: An unexpected error occurred on the server side
get:
tags:
- Correct Financial Data
summary: Fetch custom merchants for customer
description: |
Retrieves custom merchants for a given customer
operationId: corrections_v2_custom_merchants_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- corrections_v2_custom_merchants_get
data:
type: array
items:
$ref: '#/components/schemas/CustomMerchant'
example:
operation_id: corrections_v2_custom_merchants_get
data:
- custom_merchant_id: 43297d36-2d86-460f-832c-c384f319af64
name: Krystian Wines
suggested_url: https://www.example.com/
online_or_billing_only: false
created_at: '2024-11-14T12:15:52Z'
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: corrections_v2_custom_merchants_get
code_id: failed_validation
message: validation failed
errors:
validation_errors:
- X-Customer-ID header must be valid UUID
5XX:
description: An unexpected error occurred on the server side
/corrections/v2/categories/similar/{transaction_id}:
get:
tags:
- Correct Financial Data
summary: Similar Transactions
description: |-
This endpoint is used to find similar transactions to the *source* transaction. Similar transactions are determined based on transactions with similar descriptions & amounts to the source transaction.
There will **not** be any duplicate transactions in the response.
Use the `exclude_source` query parameter to toggle whether the endpoint returns the source transaction in the response. By **default** it will.
For example if there are **no** similar transactions to transaction A:
> `exclude_source = true`
>> The response will contain **0** transactions
> `exclude_source = false` or not present (**default**)
>> The response will contain **1** transaction, that being the source transaction A
operationId: corrections_v2_similar_categories_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/QueryExcludeSource'
- $ref: '#/components/parameters/PathTransactionID'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/SimilarTransactionsResponse'
examples:
Single Similar Transaction:
value:
operation_id: corrections_v2_similar_categories_get
data:
- transaction_id: source_transaction_id
account_id: 5bd9ecaf31fc2d5172fd89cb61b89fc6
provider: BankOfBud
description: paypal* specialty coffee
credit_debit_indicator: debit
status: booked
suggested_description: Pact Coffee
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/9f967c91-7cf5-46a4-bc0b-92541a4ea7da/v1/pactcoffee.jpeg
amount:
value: '10.99'
currency: GBP
date_time: '2022-05-28T10:00:00Z'
value_date_time: '2022-05-29T00:00:00Z'
merchant_category_code: '5814'
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
tokens:
- value: speciality coffee
confidence: '0.98'
website: http://www.url.com
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
processor:
id: 18f63293-0217-4520-bbf0-071dca7a9d04
slug: paypal
display_name: PayPal
logo: http://url/paypal_logo.jpeg
tokens:
- value: paypal
confidence: '0.92'
website: https://www.paypal.com
regularity:
frequency: monthly
predicted_date_times:
- '2022-06-28T15:00:00Z'
- '2022-07-28T15:00:00Z'
- '2022-08-28T15:00:00Z'
group_label: a_group_id
transaction_types:
- card
- debit
names:
- jane doe
tags:
- regular-transaction
- transaction_id: similar_transaction_id
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: Tesco 2956 London GBR
credit_debit_indicator: debit
status: booked
suggested_description: Tesco
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v2/tesco.jpeg
amount:
value: '50.23'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
value_date_time: '2022-05-27T00:00:00Z'
merchant_category_code: '5411'
enrichments:
categories:
l1:
slug: eating_out
confidence: '0.99'
l2:
slug: cafes_and_eating_out
confidence: '0.98'
merchant:
id: 0980cf54-6052-4527-84ff-e6f9b169884f
slug: tesco_stores
display_name: Tesco
logo: http://url/tesco_stores_logo.jpeg
tokens:
- value: tesco
confidence: '0.96'
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
transaction_types:
- card
- debit
metadata:
results: 2
exclude_source: false
Single Similar Transaction Excluding Source:
value:
operation_id: corrections_v2_similar_categories_get
data:
- transaction_id: similar_transaction_id
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: Tesco 2956 London GBR
credit_debit_indicator: debit
status: booked
suggested_description: Tesco
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v2/tesco.jpeg
amount:
value: '50.23'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
value_date_time: '2022-05-27T00:00:00Z'
merchant_category_code: '5411'
enrichments:
categories:
l1:
slug: eating_out
confidence: '0.99'
l2:
slug: cafes_and_eating_out
confidence: '0.98'
merchant:
id: 0980cf54-6052-4527-84ff-e6f9b169884f
slug: tesco_stores
display_name: Tesco
logo: http://url/tesco_stores_logo.jpeg
tokens:
- value: tesco
confidence: '0.96'
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
transaction_types:
- card
- debit
metadata:
results: 1
exclude_source: true
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Missing Customer Id:
value:
operation_id: corrections_v2_similar_categories_get
code_id: failed_validation
message: failed to parse request
errors:
X-Customer-Id: This value should not be blank
'404':
description: Unknown transaction
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestNotFoundResponse'
examples:
Transaction Not Found:
value:
operation_id: corrections_v2_similar_categories_get
code_id: not_found
message: transaction not found
5XX:
description: An unexpected error occurred on the server side.
/corrections/v2/merchants/similar/{transaction_id}:
get:
tags:
- Correct Financial Data
summary: Similar Transactions Including Merchants
description: |-
This endpoint is used to find similar transactions to the *source* transaction. Similar transactions are determined based on transactions with similar descriptions & amounts to the source transaction. In addition, transactions that also have the same merchant are returned.
There will **not** be any duplicate transactions in the response.
Use the `exclude_source` query parameter to toggle whether the endpoint returns the source transaction in the response. By **default** it will.
For example if there are **no** similar transactions to transaction A:
> `exclude_source = true`
>> The response will contain **0** transactions
> `exclude_source = false` or not present (**default**)
>> The response will contain **1** transaction, that being the source transaction A
operationId: corrections_v2_similar_merchants_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/QueryExcludeSource'
- $ref: '#/components/parameters/PathTransactionID'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/SimilarTransactionsIncludingMerchantsResponse'
examples:
Single Similar Transaction:
value:
operation_id: corrections_v2_similar_merchants_get
data:
- transaction_id: source_transaction_id
account_id: 5bd9ecaf31fc2d5172fd89cb61b89fc6
provider: BankOfBud
description: paypal* specialty coffee
credit_debit_indicator: debit
status: booked
suggested_description: Pact Coffee
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/9f967c91-7cf5-46a4-bc0b-92541a4ea7da/v1/pactcoffee.jpeg
amount:
value: '10.99'
currency: GBP
date_time: '2022-05-28T10:00:00Z'
value_date_time: '2022-05-29T00:00:00Z'
merchant_category_code: '5814'
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
tokens:
- value: speciality coffee
confidence: '0.98'
website: http://www.url.com
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
processor:
id: 18f63293-0217-4520-bbf0-071dca7a9d04
slug: paypal
display_name: PayPal
logo: http://url/paypal_logo.jpeg
tokens:
- value: paypal
confidence: '0.92'
website: https://www.paypal.com
regularity:
frequency: monthly
predicted_date_times:
- '2022-06-28T15:00:00Z'
- '2022-07-28T15:00:00Z'
- '2022-08-28T15:00:00Z'
group_label: a_group_id
transaction_types:
- card
- debit
names:
- jane doe
tags:
- regular-transaction
- transaction_id: similar_transaction_id
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: Tesco 2956 London GBR
credit_debit_indicator: debit
status: booked
suggested_description: Tesco
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v2/tesco.jpeg
amount:
value: '50.23'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
value_date_time: '2022-05-27T00:00:00Z'
merchant_category_code: '5411'
enrichments:
categories:
l1:
slug: eating_out
confidence: '0.99'
l2:
slug: cafes_and_eating_out
confidence: '0.98'
merchant:
id: 0980cf54-6052-4527-84ff-e6f9b169884f
slug: tesco_stores
display_name: Tesco
logo: http://url/tesco_stores_logo.jpeg
tokens:
- value: tesco
confidence: '0.96'
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
transaction_types:
- card
- debit
metadata:
results: 2
exclude_source: false
Single Similar Transaction Excluding Source:
value:
operation_id: corrections_v2_similar_merchants_get
data:
- transaction_id: similar_transaction_id
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: Tesco 2956 London GBR
credit_debit_indicator: debit
status: booked
suggested_description: Tesco
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v2/tesco.jpeg
amount:
value: '50.23'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
value_date_time: '2022-05-27T00:00:00Z'
merchant_category_code: '5411'
enrichments:
categories:
l1:
slug: eating_out
confidence: '0.99'
l2:
slug: cafes_and_eating_out
confidence: '0.98'
merchant:
id: 0980cf54-6052-4527-84ff-e6f9b169884f
slug: tesco_stores
display_name: Tesco
logo: http://url/tesco_stores_logo.jpeg
tokens:
- value: tesco
confidence: '0.96'
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
transaction_types:
- card
- debit
metadata:
results: 1
exclude_source: true
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Missing Customer Id:
value:
operation_id: corrections_v2_similar_merchants_get
code_id: failed_validation
message: failed to parse request
errors:
X-Customer-Id: This value should not be blank
'404':
description: Unknown transaction
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestNotFoundResponse'
examples:
Transaction Not Found:
value:
operation_id: corrections_v2_similar_merchants_get
code_id: not_found
message: transaction not found
5XX:
description: An unexpected error occurred on the server side.
/corrections/v2/merchant-feedback/merchant/{merchant_id}:
post:
tags:
- Correct Financial Data
summary: Suggests changes to a merchant
description: |
Records feedback we can use to improve our merchant database.
operationId: corrections_v2_merchant_feedback_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- name: merchant_id
in: path
required: true
description: The ID of the merchant to submit feedback for.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MerchantFeedbackRequest'
responses:
'202':
description: Accepted
content:
application/json:
schema:
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- corrections_v2_merchant_feedback_post
data:
$ref: '#/components/schemas/MerchantFeedbackResponse'
example:
operation_id: corrections_v2_merchant_feedback_post
data:
merchant_id: a8f0ec99-ed01-4ba2-a4ad-8d0275f15158
logo_feedback: missing_logo
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: corrections_v2_merchant_feedback_post
code_id: failed_validation
message: validation failed
errors:
validation_errors:
- $.logo_feedback must be valid enum
'404':
description: The merchant was not found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestNotFoundResponse'
example:
operation_id: unknown
code_id: unknown
message: Route or resource not found
errors: {}
5XX:
description: An unexpected error occurred on the server side
/goals/v1/spending-budgets:
post:
tags:
- Spending Budgets
summary: Create Spending Budget
description: |
Create a spending budget.
operationId: goals_v1_spending_budgets_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpendingBudgetRequest'
example:
name: Travel Budget
amount:
value: '300.00'
currency: GBP
recurrency:
period: monthly
starting_day: 1
include:
categories:
- l1: travel
merchants:
slugs:
- uber
responses:
'201':
description: Created - The budget was created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpendingBudgetResponse'
example:
operation_id: goals_v1_spending_budgets_post
data:
id: f46d76c4-56d3-11ee-ac69-d6df71eb5902
name: Travel Budget
amount:
value: '300.00'
currency: GBP
recurrency:
period: monthly
starting_day: 1
include:
categories:
- l1: travel
merchants:
slugs:
- uber
spent:
from: '2023-10-19'
to: '2023-10-31'
amount:
value: '160.59'
currency: GBP
ratio: '0.54'
created_at: '2023-10-03T09:20:30Z'
_links:
transactions: /goals/v1/spending-budgets/f46d76c4-56d3-11ee-ac69-d6df71eb5902/transactions
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
get:
tags:
- Spending Budgets
summary: Retrieve Spending Budgets
description: |
Retrieve all spending budgets.
Accounts IDs can be supplied as part of the URL query to return budgets with values filtered to the accounts IDs supplied. These budgets'
spent amounts will only consider transactions associated with the specified accounts.
If no account IDs are specified, the returned budgets will have a value combined from transactions across all of the customer's accounts.
operationId: goals_v1_spending_budgets_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/QueryBudAccountID'
- $ref: '#/components/parameters/QueryDay'
responses:
'200':
description: OK - The spending budgets were retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveSpendingBudgetsResponse'
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
delete:
tags:
- Spending Budgets
summary: Delete all Spending Budgets
description: |
Delete all of a customers' spending budgets.
operationId: goals_v1_spending_budgets_delete_all
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
responses:
'204':
description: No Content - The budgets were removed successfully.
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
'404':
description: Not Found - The customer has no budgets to be deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
/goals/v1/spending-budgets/{budget_id}:
patch:
tags:
- Spending Budgets
summary: Patch a Spending Budget
description: |
Update a Spending Budget with a given `budget_id`.
operationId: goals_v1_spending_budgets_patch
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/PathSpendingBudgetID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchSpendingBudget'
responses:
'200':
description: OK - The budget was updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSpendingBudgetResponse'
example:
operation_id: goals_v1_spending_budgets_patch
data:
id: f46d76c4-56d3-11ee-ac69-d6df71eb5902
name: Travel Budget
amount:
value: '300.00'
currency: GBP
recurrency:
period: monthly
starting_day: 1
include:
categories:
- l1: travel
merchants:
slugs:
- uber
spent:
from: '2023-10-19'
to: '2023-10-31'
amount:
value: '160.59'
currency: GBP
ratio: '0.54'
created_at: '2023-10-03T09:20:30Z'
_links:
transactions: /goals/v1/spending-budgets/f46d76c4-56d3-11ee-ac69-d6df71eb5902/transactions
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
'404':
description: Not Found - The goal ID could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
delete:
tags:
- Spending Budgets
summary: Delete a Spending Budget
description: |
Delete a specific spending budget with the given `budget_id`
operationId: goals_v1_spending_budgets_delete
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/PathSpendingBudgetID'
responses:
'204':
description: No Content - The budget was removed successfully.
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
'404':
description: Not Found - The budget could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
/goals/v1/spending-budgets/{budget_id}/transactions:
get:
tags:
- Spending Budgets
summary: Retrieve Spending Budget Transactions
description: |
Retrieve all of the transactions associated with a spending budget. The results of this endpoint are paginated with a default page size of `100` and a maximum of `200`.
The page size is configurable by the `page_size` query parameter.
The next page of results can be retrieved using the `page_token` query parameter.
Account IDs can be supplied as part of the URL query to filter transactions to those only associated with the specified accounts.
If no account IDs are specified, we will return transactions associated with all of the customer's accounts, relevant to the spending budget.
operationId: goals_v1_spending_budget_transactions_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/PathSpendingBudgetID'
- $ref: '#/components/parameters/QueryDay'
- $ref: '#/components/parameters/parameters-QueryBudPageToken'
- $ref: '#/components/parameters/parameters-QueryBudPageSize'
- $ref: '#/components/parameters/QueryBudAccountID'
responses:
'200':
description: OK - The spending budget transactions were retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveSpendingBudgetTransactionsResponse'
example:
operation_id: goals_v1_spending_budget_transactions_get
data:
- transaction_id: fbdc28e82f0f137586a526a88ec4a6be
account_id: RxsYshVGded4JeilkXgWKdXA
provider: BankOfBud
description: uber taxi
credit_debit_indicator: debit
status: booked
amount:
value: '16.39'
currency: GBP
date_time: '2023-10-03T10:00:00Z'
enrichments:
categories:
l1:
slug: transport
confidence: '0.99'
l2:
slug: taxi
confidence: '0.99'
merchant:
id: 9f345fcb-d1ee-4e79-a23e-510fb8dbd61f
slug: uber
display_name: Uber
logo: https://url/uber_logo.jpeg
suggested_description: Uber
metadata:
results: 1
page_token: b21055a9a9f46fc794a2e6855c65abd7e317181039fc6930daabac5822911d14a84895ecd947e2b5abdcb22e4fcc2c594e1f661dc63e34b9ba88760724047990896f7581a0786c2605dce19c6a9d80d1044f963b74fea0a929c0a4465a6e67378a74dce38ec5e26ae4cc804b62fd666d5df4cf2e7f524bd99e5523bc5d471768065c036dc0c73122705b280817fbbd7d9aa31f271d72cd3877d999dcb9a5b1c0be0c05
page_size: 100
budget_id: 19d1def3-5860-11ee-9342-3e1d60bc76f9
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
/goals/v2/savings/goal:
post:
tags:
- Savings Goals V2
summary: Create Savings Goal V2
description: |
Create a savings goal for the given account.
The `allocation_ratio` defines the proportion of the account balance that is considered allocated to this goal. For example, an `allocation_ratio` of `0.2` means that 20% of the account balance is treated as the goal balance.
The `goal_balance` returned in the response is calculated as the current account balance multiplied by the `allocation_ratio`.
operationId: goals_v2_savings_goal_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSavingsGoalV2Request'
example:
account_id: RxsYshVGded4JeilkXgWKdXA
name: Car Savings
target_amount:
value: '3000.00'
currency: GBP
target_datetime: '2025-12-30T00:00:00Z'
allocation_ratio: 0.2
responses:
'200':
description: OK - The goal was created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSavingsGoalV2Response'
example:
operation_id: goals_v2_savings_goal_post
data:
id: f46d76c4-56d3-11ee-ac69-d6df71eb5902
account_id: RxsYshVGded4JeilkXgWKdXA
name: Car Savings
target_amount:
currency: GBP
value: '3000.00'
target_datetime: '2025-12-30T00:00:00Z'
allocation_ratio: 0.2
goal_balance:
currency: GBP
value: '500.00'
created_at: '2024-01-15T10:04:43Z'
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Customer ID Missing:
value:
operation_id: goals_v2_savings_goal_post
code_id: failed_validation
message: unable to validate request
errors:
X-Customer-ID: 'parameter "X-Customer-ID" in header has an error: value is required but missing'
Invalid Allocation Ratio:
value:
operation_id: goals_v2_savings_goal_post
code_id: failed_validation
message: Invalid request payload.
errors:
allocation_ratio:
- must be greater than 0 and at most 1
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/goals/v2/savings/goals:
get:
tags:
- Savings Goals V2
summary: Retrieve Savings Goals V2
description: |
Retrieve all savings goals for the customer. The results can be filtered by the `account_id` query parameter.
The `goal_balance` for each goal is calculated as the current account balance multiplied by the `allocation_ratio`.
operationId: goals_v2_savings_goals_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/QueryBudAccountID'
responses:
'200':
description: OK - The goals were retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveSavingsGoalsV2Response'
examples:
Goals Returned:
value:
operation_id: goals_v2_savings_goals_get
data:
- id: f46d76c4-56d3-11ee-ac69-d6df71eb5902
account_id: RxsYshVGded4JeilkXgWKdXA
name: Car Savings
target_amount:
currency: GBP
value: '3000.00'
target_datetime: '2025-12-30T00:00:00Z'
allocation_ratio: 0.2
goal_balance:
currency: GBP
value: '500.00'
created_at: '2024-01-15T10:04:43Z'
- id: 265a4aed-348d-4ff1-802e-2d08d7cace77
account_id: RxsYshVGded4JeilkXgWKdXA
name: Holiday Savings
target_amount:
currency: GBP
value: '1000.00'
allocation_ratio: 0.1
goal_balance:
currency: GBP
value: '250.00'
created_at: '2024-01-15T10:04:43Z'
No Goals Exist:
value:
operation_id: goals_v2_savings_goals_get
data: []
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Customer ID Missing:
value:
operation_id: goals_v2_savings_goals_get
code_id: failed_validation
message: unable to validate request
errors:
X-Customer-ID: 'parameter "X-Customer-ID" in header has an error: value is required but missing'
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/goals/v2/savings/goals/{savings_goal_id}:
get:
tags:
- Savings Goals V2
summary: Retrieve Savings Goal V2
description: |
Retrieve a savings goal by its `savings_goal_id`.
The `goal_balance` is calculated as the current account balance multiplied by the `allocation_ratio`.
operationId: goals_v2_savings_goal_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/PathSavingsGoalIDV2'
responses:
'200':
description: OK - The goal was retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveSavingsGoalV2Response'
example:
operation_id: goals_v2_savings_goal_get
data:
id: f46d76c4-56d3-11ee-ac69-d6df71eb5902
account_id: RxsYshVGded4JeilkXgWKdXA
name: Car Savings
target_amount:
currency: GBP
value: '3000.00'
target_datetime: '2025-12-30T00:00:00Z'
allocation_ratio: 0.2
goal_balance:
currency: GBP
value: '500.00'
created_at: '2024-01-15T10:04:43Z'
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Customer ID Missing:
value:
operation_id: goals_v2_savings_goal_get
code_id: failed_validation
message: unable to validate request
errors:
X-Customer-ID: 'parameter "X-Customer-ID" in header has an error: value is required but missing'
Invalid Goal ID:
value:
operation_id: goals_v2_savings_goal_get
code_id: failed_validation
message: Invalid request payload.
errors:
savings_goal_id:
- invalid UUID format
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'404':
description: Not Found - The savings goal ID could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Route or resource not found
errors: {}
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
patch:
tags:
- Savings Goals V2
summary: Update Savings Goal V2
description: |
Update a savings goal with the given `savings_goal_id`. All fields are optional.
The `goal_balance` returned in the response is recalculated as the current account balance multiplied by the updated `allocation_ratio`.
operationId: goals_v2_savings_goal_patch
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/PathSavingsGoalIDV2'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSavingsGoalV2Request'
examples:
Name Updated:
value:
name: Mortgage Deposit Savings
Allocation Ratio and Target Date Updated:
value:
allocation_ratio: 0.25
target_datetime: '2026-06-30T00:00:00Z'
responses:
'200':
description: OK - The goal was updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSavingsGoalV2Response'
example:
operation_id: goals_v2_savings_goal_patch
data:
id: f46d76c4-56d3-11ee-ac69-d6df71eb5902
account_id: RxsYshVGded4JeilkXgWKdXA
name: Mortgage Deposit Savings
target_amount:
currency: GBP
value: '3000.00'
target_datetime: '2026-06-30T00:00:00Z'
allocation_ratio: 0.25
goal_balance:
currency: GBP
value: '625.00'
created_at: '2024-01-15T10:04:43Z'
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Customer ID Missing:
value:
operation_id: goals_v2_savings_goal_patch
code_id: failed_validation
message: unable to validate request
errors:
X-Customer-ID: 'parameter "X-Customer-ID" in header has an error: value is required but missing'
Invalid Allocation Ratio:
value:
operation_id: goals_v2_savings_goal_patch
code_id: failed_validation
message: Invalid request payload.
errors:
allocation_ratio:
- must be greater than 0 and at most 1
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'404':
description: Not Found - The savings goal ID could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Route or resource not found
errors: {}
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
delete:
tags:
- Savings Goals V2
summary: Remove Savings Goal V2
description: |
Remove a savings goal with the given `savings_goal_id`.
operationId: goals_v2_savings_goal_delete
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/PathSavingsGoalIDV2'
responses:
'204':
description: No Content - The goal was removed successfully.
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Invalid Goal ID:
value:
operation_id: goals_v2_savings_goal_delete
code_id: failed_validation
message: Invalid request payload.
errors:
savings_goal_id:
- invalid UUID format
'401':
description: Unauthorized - The request was not authorised.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'404':
description: Not Found - The savings goal ID could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Route or resource not found
errors: {}
'500':
description: Internal Server Error - An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/v1/regular-transactions:
get:
tags:
- Regular Payments Finder
summary: Retrieve Regular Transactions
description: |
Provides a list of customer transactions that occur regularly. Currently the following periods are supported:
- `daily`
- `weekly`
- `biweekly`
- `monthly`
- `quarterly`
- `unknown`
operationId: regular_transactions_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
responses:
'200':
description: The request was successfully processed
content:
application/json:
schema:
$ref: '#/components/schemas/RegularTransactionsResponse'
example:
operation_id: regular_transactions_get
data:
- label: 7fa6c13ac15468dd61cc7680f005b1dcdd9504d7-0
period: monthly
score: '0.9892'
transactions:
- provider: Barclays
account_id: 688cb2e1-fca9-4d77-bbd3-604abb3c9d46
transaction_id: 3c6f2abd-87ff-4b57-b7c7-c500926571e7
transaction_description: Bank credit paypal
date: 2019-07-04T00:00:00+0000
amount:
amount: '49.99'
currency: GBP
credit_debit_indicator: Debit
merchant:
id: paypal
name: PayPal
logo: https://assets.thisisbud.com/bud-datasci-images/merchant_logos/a3af57fc-ec8a-4258-a8da-8d34f11640f6/v1/paypal.jpeg
- provider: Barclays
account_id: 688cb2e1-fca9-4d77-bbd3-604abb3c9d46
transaction_id: d06bef46-7500-4d34-a419-bb2c5e4ee9fa
transaction_description: Bank credit paypal
date: 2019-08-04T00:00:00+0000
amount:
amount: '52.3'
currency: GBP
credit_debit_indicator: Debit
merchant:
id: paypal
name: PayPal
logo: https://assets.thisisbud.com/bud-datasci-images/merchant_logos/a3af57fc-ec8a-4258-a8da-8d34f11640f6/v1/paypal.jpeg
- label: 8a29913437a6d2e72a9576a15593f43d92cfc2eb-0
period: monthly
score: '0.9892'
transactions:
- provider: Lloyds
account_id: 688cb2e1-fca9-4d77-bbd3-604abb3c9d46
transaction_id: c5a50ce9-5523-47b4-8c08-3cd8e30e34a6
transaction_description: Foxtons - Rent
date: 2019-06-02T00:00:00+0000
amount:
amount: '1325'
currency: GBP
credit_debit_indicator: Debit
merchant:
id: foxtonslimited
name: FOXTONS LIMITED
logo: https://assets.thisisbud.com/bud-datasci-images/merchant_logo_placeholder.png
- provider: Lloyds
account_id: 688cb2e1-fca9-4d77-bbd3-604abb3c9d46
transaction_id: 70778a02-ea30-4465-b651-65189fd3c51d
transaction_description: Foxtons - Rent
date: 2019-07-02T00:00:00+0000
amount:
amount: '1325'
currency: GBP
credit_debit_indicator: Debit
merchant:
id: foxtonslimited
name: FOXTONS LIMITED
logo: https://assets.thisisbud.com/bud-datasci-images/merchant_logo_placeholder.png
'204':
description: No transactions found
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: regular_transactions_get
code_id: failed_validation
message: Failed validation
errors:
client_id: This value should not be blank
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v2/future-transactions:
get:
tags:
- Regular Payments Finder
summary: Retrieve Future Transactions V2
description: |
Provides a list of transactions predicted to occur in the next specified number of months. Currently the following periods are supported:
- `daily`
- `weekly`
- `biweekly`
- `monthly`
- `quarterly`
- `unknown`
operationId: v2_future_transactions_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/FutureTransactionsMonthsProjection'
- $ref: '#/components/parameters/FutureTransactionsChangePercentage'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FutureTransactionV2Response'
example:
operation_id: v2_future_transactions_get
data:
- transaction_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
account_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
transaction_description: Energy Bill
label: 8a29913437a6d2e72a9576a15593f43d92cfc2eb-0
period: monthly
date_time: '2019-07-01T01:00:00Z'
amount:
value: '100.00'
currency: GBP
credit_debit_indicator: debit
confidence: '0.9892'
categories:
l1:
slug: utilities
confidence: '1.00'
l2:
slug: utilities_energy
future_transactions:
- date: '2022-08-01'
amount:
value: '102.00'
currency: GBP
- date: '2022-09-01'
amount:
value: '104.04'
currency: GBP
- date: '2022-10-01'
amount:
value: '106.12'
currency: GBP
- date: '2022-11-01'
amount:
value: '108.24'
currency: GBP
metadata:
results: 1
months: 4
change_percentages:
- l2: utilities_energy
value: 2
'204':
description: No transactions
'400':
description: Bad request
'401':
description: Unauthorized request
/v2/income:
get:
tags:
- Income Finder
summary: Retrieve Income Transactions V2
description: |
Provides a list of a customer's income based transactions found within their connected accounts, and predicts whether each income transaction is related to a customer's `salary_or_wages`. Any income which is not salary or wages is given the type `other_incoming`, which can include other income sources such as investments or pension income.
When `X-From` is omitted from the request, a default value of 9 months from before today's date will be used.
When `X-To` is omitted from the request, a default value of today's date will be used.
**Notes:**
- Transactions with multiple currencies are supported, but the statistics are currently only calculated for one currency. The endpoint takes the currency of the first transaction and ignores non-matching currencies in its calculations.
- In contrast to the V1 endpoint, Income Finder V2 no longer filters income transactions to only return the latest per reference.
operationId: v2_income_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/SmartFinderFrom'
- $ref: '#/components/parameters/SmartFinderTo'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IncomeResponseV2'
example:
operation_id: v2_income_get
data:
transactions:
- transaction_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
account_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
transaction_description: PayPal* Bud
provider: Barclays
date: 2021-01-11T01:00:00+0100
amount:
value: '1234.56'
currency: GBP
credit_debit_indicator: Credit
enrichment:
categories:
l1:
- name: finances
confidence: '0.8057'
label: Finances
l2:
- name: transfers_in
confidence: '0.7811'
label: Transfers In
l3:
- name: salary
confidence: '0.6805'
label: Salary
merchant:
id: bud
name: Bud
logo: https://thisisbud.com/merchants/bud.png
confidence: '0.9501'
processor:
id: paypal
name: PayPal
logo: https://thisisbud.com/processors/paypal.png
confidence: '0.9702'
income:
type: salary_or_wages
confidence: '0.9408'
statistics:
average:
monthly:
income:
value: '1234.56'
currency: GBP
regular_income:
value: '1234.56'
currency: GBP
metadata:
from: '2021-01-01'
to: '2021-01-31'
results: 1
'204':
description: No transactions
'400':
description: Bad request
'401':
description: Unauthorised request
'404':
description: No transactions found
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/benefits:
get:
tags:
- Income Finder
summary: Retrieve Benefits Transactions
description: |
Provides a list of a customer's benefits based transactions found within their connected accounts.
When `X-From` is omitted from the request, a default value of 30 days from before today's date will be used.
When `X-To` is omitted from the request, a default value of today's date will be used.
operationId: v1_benefits_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/SmartFinderFrom'
- $ref: '#/components/parameters/SmartFinderTo'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BenefitsResponseV1'
example:
operation_id: v1_benefits_get
data:
- transaction_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
account_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
transaction_description: NATWEST DWP DLA GBR
provider: Natwest
date: 2022-03-21T01:00:00+0100
amount:
amount: '333.28'
currency: GBP
credit_debit_indicator: Credit
benefit:
type: disability_living_allowance
display_name: Disability Living Allowance
metadata:
from: '2022-03-19'
to: '2022-04-19'
results: 1
'204':
description: No transactions
'400':
description: Bad request
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/benefits/totals:
get:
tags:
- Income Finder
summary: Retrieve Benefits Totals
description: |
Provides a customers' total income under each detected benefit type.
When `X-From` is omitted from the request, a default value of 30 days from before today's date will be used.
When `X-To` is omitted from the request, a default value of today's date will be used.
operationId: v1_benefits_totals_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/SmartFinderFrom'
- $ref: '#/components/parameters/SmartFinderTo'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BenefitsTotalsResponseV1'
example:
operation_id: v1_benefits_get_totals
data:
- benefit:
type: disability_living_allowance
display_name: Disability Living Allowance
total_credit:
value: '333.28'
currency: GBP
metadata:
from: '2022-03-19'
to: '2022-04-19'
results: 1
'204':
description: No transactions found
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: merchants_totals_get
code_id: failed_validation
message: Failed validation
errors:
client_id: This value should not be blank
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/loans:
get:
tags:
- Loan Finder
summary: Retrieve Loan Transactions
description: |
Provides a list of a customers' outgoing loan transactions found within their connected accounts.
When `X-From` is omitted from the request, a default value of 30 days from before today's date will be used.
When `X-To` is omitted from the request, a default value of today's date will be used.
**Notes:**
- Transactions with multiple currencies are supported, but the statistics are currently only calculated for one currency. The endpoint takes the currency of the first transaction and ignores non-matching currencies in its calculations.
operationId: v1_loans_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/SmartFinderFrom'
- $ref: '#/components/parameters/SmartFinderTo'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LoansResponseV1'
example:
operation_id: v1_loans_get
data:
transactions:
- transaction_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
account_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
transaction_description: Bud Loan Repayment
provider: Natwest
date: 2022-03-21T01:00:00+0100
amount:
value: '133.28'
currency: GBP
credit_debit_indicator: Debit
merchant:
id: bud
name: Bud
logo: https://thisisbud.com/merchants/bud.png
confidence: '0.875'
statistics:
total_debit:
value: '133.28'
currency: GBP
metadata:
results: 1
from: '2022-03-19'
to: '2022-04-19'
'204':
description: No transactions
'400':
description: Bad request
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/debt-collection:
get:
tags:
- Debt Collection Finder
summary: Retrieve Debt Collection Transactions
description: |
Provides a list of a customers' outgoing debt collection transactions found within their connected accounts.
When `X-From` is omitted from the request, a default value of 30 days from before today's date will be used.
When `X-To` is omitted from the request, a default value of today's date will be used.
**Notes:**
- Transactions with multiple currencies are supported, but the statistics are currently only calculated for one currency.
The endpoint takes the currency of the first transaction and ignores non-matching currencies in its calculations.
operationId: v1_debt_collection_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/SmartFinderFrom'
- $ref: '#/components/parameters/SmartFinderTo'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DebtCollectionResponseV1'
example:
operation_id: v1_debt_collection_get
data:
transactions:
- transaction_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
account_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
transaction_description: Bud Debt Collection Payment
provider: Barclays
date: 2021-04-11T01:00:00+0100
amount:
value: '100.00'
currency: GBP
credit_debit_indicator: Debit
merchant:
id: debtcollector
name: Debt Collector
logo: https://thisisbud.com/merchants/debtcollector.png
confidence: '0.12345'
statistics:
total_debit:
value: '100.00'
currency: GBP
income_relations:
expense_to_income_ratio: '0.100'
total_income:
value: '1000.00'
currency: GBP
metadata:
results: 1
from: '2022-03-19'
to: '2022-04-19'
'204':
description: No transactions
'400':
description: Bad request
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/insights/v2/products:
get:
tags:
- Product Finder
summary: Retrieve Financial Products V2
description: |
Financial Products returns the finance oriented products and services that a customer uses.
This endpoint generates data using a customer's transaction history.
Financial Products detects the following types of products and services:
- Loans
- Buy Now, Pay Later (BNPL)
- Mortgages
- Insurance products
- Credit Cards
- Private Pensions
- Savings and Investments
*Notes:*
- If from and to parameters are not set, this endpoint will default to using transactions from the last six months.
> 🚧 Limitations
>
> Financial Products are only identified from debit transactions.
operationId: insights_v2_products
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/QueryFromDate'
- $ref: '#/components/parameters/QueryToDate'
responses:
'200':
description: OK - everything worked as expected
content:
application/json:
schema:
$ref: '#/components/schemas/GetProductsResponseV2'
example:
operation_id: insights_v2_products
data:
- type:
- credit_card
merchant:
id: nationwidebuildingsociety
logo: https://assets.thisisbud.com/bud-datasci-images/merchant_logos/e121c7aa-a254-41bb-ad3e-33b988f791be/v1/nationwidebuildingsociety.jpeg
name: Nationwide Building Society
amount:
value: '0.03'
currency: GBP
period: unknown
- type:
- insurance
merchant:
id: aviva
logo: https://assets.thisisbud.com/bud-datasci-images/merchant_logos/c50be401-7891-44c5-9fed-535080e77c57/v1/aviva.jpeg
name: Aviva
amount:
value: '59.99'
currency: GBP
period: monthly
metadata:
from: '2022-09-03T11:28:22.00Z'
to: '2023-03-03T11:28:22.00Z'
results: 2
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: insights_v2_products
code_id: failed_validation
message: Invalid request payload.
errors:
from: 'invalid ''from'' date: ''7th March 2023'''
'401':
description: Unauthorised Request - the request was not authenticated or authorised
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: Unauthorised request
'500':
description: Server Error - an unexpected error occurred on the server side
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
example:
operation_id: unknown
code_id: unknown
message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
/v1/subscriptions:
get:
tags:
- Subscription Finder
summary: Retrieve Subscriptions
description: |
This endpoint is used to retrieve information about a user's subscriptions
When `X-From` is omitted from the request, a default value of 30 days from before today's date will be used.
When `X-To` is omitted from the request, a default value of today's date will be used.
operationId: v1_subscriptions_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/SmartFinderFrom'
- $ref: '#/components/parameters/SmartFinderTo'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetSubscriptionsResponseV1'
example:
operation_id: v1_subscriptions_get
data:
- subscription_type: media_streaming
period: monthly
categories:
l1: media_and_telecoms
l2: tv_streaming_services
merchant:
id: netflix
name: Netflix
logo: https://assets.thisisbud.com/netflix_logo_placeholder.jpeg
transactions:
- transaction_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
account_id: an_account_id
transaction_description: Netflix
provider: Barclays
date: 2022-03-21T01:00:00+0100
amount:
value: '9.99'
currency: GBP
credit_debit_indicator: Debit
- transaction_id: hdcc55c6-f347-4abc-8c66-61ff290d8bd4
account_id: an_account_id
transaction_description: Netflix
provider: Barclays
date: 2022-04-21T01:00:00+0100
amount:
value: '9.99'
currency: GBP
credit_debit_indicator: Debit
- subscription_type: unknown
period: unknown
categories:
l1: general
l2: other_general
transactions:
- transaction_id: idcc55c6-f347-4abc-8c66-61ff290d8bd4
account_id: an_account_id
transaction_description: A Random Subscription Payment
provider: Barclays
date: 2022-05-11T01:00:00+0100
amount:
value: '59.99'
currency: GBP
credit_debit_indicator: Debit
metadata:
results: 2
from: '2022-03-19'
to: '2022-05-19'
'204':
description: No subscriptions found
'400':
description: The request contains an invalid payload.
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/search/beta/transactions:
get:
tags:
- Transaction Search
summary: Search customer transactions.
description: |-
Finds the most relevant transactions matching the `user_input` text.
An initial free text search will then suggest `suggested_searches` which use structured data e.g. `category_l1` or `merchant_name`.
At most one of the following query parameters can be used per request, if multiple are set the endpoint will return a `Bad Request` response (if none are set, transactions will be returned with no filtering to facilitate showing an initial transaction list to the user):
- `user_input`
- `merchant_name`
- `category_l1`
- `category_l2`
- `description`
- `tag`
This endpoint also provides a link to view an AI-generated insight about the current search. Please wait for the allotted `insight.url_delay` before following this link to avoid unnecessary polling before the insight has been generated.
operationId: search_beta_transactions_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/HeaderTimezone'
- $ref: '#/components/parameters/HeaderSearchTransactionsAccept'
- $ref: '#/components/parameters/QueryUserInput'
- $ref: '#/components/parameters/QueryMerchantName'
- $ref: '#/components/parameters/QueryCategoryL1'
- $ref: '#/components/parameters/QueryCategoryL2'
- $ref: '#/components/parameters/QueryDescription'
- $ref: '#/components/parameters/QueryTag'
- $ref: '#/components/parameters/QueryAccountId'
- $ref: '#/components/parameters/QueryCreditDebitIndicator'
- $ref: '#/components/parameters/QueryAmountMin'
- $ref: '#/components/parameters/QueryAmountMax'
- $ref: '#/components/parameters/QueryFromBudDate'
- $ref: '#/components/parameters/QueryToBudDate'
- $ref: '#/components/parameters/QueryBudPageToken'
- $ref: '#/components/parameters/QueryBudPageSize'
responses:
'200':
$ref: '#/components/responses/SearchTransactionsResponse'
'400':
description: Bad Request
/search/beta/transactions/{search_id}:
get:
tags:
- Transaction Search
summary: Get transaction search by ID.
description: |-
Retrieves an existing transaction search by its search ID.
**📘 Note: Searches are transient. After the search expires (see `metadata.expires_in`), this endpoint will return a `Not Found` response. The recommended behaviour in this case is to resubmit the desired search using the `Search customer transactions` endpoint.**
operationId: search_beta_transactions_search_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/PathSearchId'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/HeaderTimezone'
- $ref: '#/components/parameters/HeaderSearchTransactionsAccept'
- $ref: '#/components/parameters/QueryBudPageToken'
- $ref: '#/components/parameters/QueryBudPageSize'
responses:
'200':
$ref: '#/components/responses/SearchTransactionsResponse'
'404':
description: Not Found
/search/beta/transactions/{search_id}/insight:
get:
tags:
- Transaction Search
summary: Get transaction search insight.
description: |-
Retrieves an AI-generated insight to enrich the output, or answer the question asked in the input to the transaction search. There is no multi-currency support in insights, so the default currency for the customer's region will be assumed.
This insight can take some time to generate, so the `status` property can be used in combination with the `Retry-After` response header to poll until the insight is generated (at which point the status will be `success`).
**📘 Note: Searches are transient. After the search expires (see `metadata.expires_in`), this endpoint will return a `Not Found` response. The recommended behaviour in this case is to resubmit the desired search using the `Search customer transactions` endpoint.**
operationId: search_beta_transactions_insight_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/PathSearchId'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/HeaderTimezone'
responses:
'200':
$ref: '#/components/responses/SearchTransactionsInsightResponse'
'404':
description: Not Found
/search/beta/transactions/{search_id}/insight/transactions:
get:
tags:
- Transaction Search
summary: Get transactions used by the search insight.
description: |-
Retrieves transactions used to calculate the AI-generated transaction search insight, to provide explainability for the insight.
This insight can take some time to generate, so until the insight is generated (use the insight endpoint to check status), this endpoint will return a `Not Found` response.
**📘 Note: Searches are transient. After the search expires (see `metadata.expires_in`), this endpoint will return a `Not Found` response. The recommended behaviour in this case is to resubmit the desired search using the `Search customer transactions` endpoint.**
operationId: search_beta_transactions_insight_transactions_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/PathSearchId'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/HeaderTimezone'
- $ref: '#/components/parameters/HeaderSearchTransactionsAccept'
- $ref: '#/components/parameters/QueryBudPageToken'
- $ref: '#/components/parameters/QueryBudPageSize'
responses:
'200':
$ref: '#/components/responses/SearchInsightTransactionsResponse'
'404':
description: Not Found
/assess/v1/customer-applications:
post:
tags:
- Customer Applications
summary: Create Customer Application
description: |
Create a new customer application.
Applications can hold more data than just the standard Bud Customer
information, such as:
- Applicant First Name
- Applicant Last Name
- Names for Secondary Applicants (if this is a joint application)
- Key-value pairs for additional metadata you may want to associate to
this application (e.g. if the customer is applying for finance, your
system may have a product code for the relevant finance product).
operationId: v1_customer_applications_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostCustomerApplicationsRequest'
example:
primary_applicant:
first_name: John
last_name: Doe
secondary_applicants:
- first_name: Jane
last_name: Doe
financial_data_consent: one_time
metadata:
loan_product_code: credit_card_1234
responses:
'201':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/PostCustomerApplicationsResponse'
example:
operation_id: v1_customer_applications_post
data:
application_id: 48ac72d0-a829-4896-a067-dcb1c2b0f30c
customer_id: 160c0c4b-9966-4dc1-a916-8407eb10d74e
expires_at: '2023-05-11T15:30:39Z'
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
get:
tags:
- Customer Applications
summary: Retrieve Customer Applications
description: |
Retrieve a list of all your customer applications.
operationId: v1_customer_applications_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/MetadataFieldName'
- $ref: '#/components/parameters/PageToken'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomerApplicationsResponse'
example:
operation_id: v1_customer_applications_get
data:
- application_id: 48ac72d0-a829-4896-a067-dcb1c2b0f30c
creation_date: '2023-04-11T15:30:39Z'
deletion_date: '2023-05-11T15:30:39Z'
customer_id: 160c0c4b-9966-4dc1-a916-8407eb10d74e
initiator_id: 06588898-9a84-4b35-ba8f-f9cbd64946f3
primary_applicant:
first_name: John
last_name: Doe
secondary_applicants:
- first_name: Jane
last_name: Doe
accounts_connected: 0
customer_link:
created_at: '2023-04-11T15:31:39Z'
url: https://path-to-customer-link/b5daa5f7-b993-42e9-a232-76057151bacf
finished_connecting_accounts: false
expired: false
status: requested
review_status: ''
review_date: '2023-05-11T15:30:39Z'
financial_data_consent: one_time
metadata:
loan_product_code: credit_card_1234
metadata:
results: 1
next_page_token: 4jmBrvVn9r
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/assess/v1/customer-applications/{application_id}:
get:
tags:
- Customer Applications
summary: Retrieve Customer Application
description: |
Retrieve an individual customer's application.
operationId: v1_customer_application_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerApplicationID'
- $ref: '#/components/parameters/Timezone'
- $ref: '#/components/parameters/DateRangeEnd'
- $ref: '#/components/parameters/DateRangeDurations'
responses:
'200':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomerApplicationResponse'
example:
operation_id: v1_customer_application_get
data:
application_id: 48ac72d0-a829-4896-a067-dcb1c2b0f30c
organisation_id: 9ec26450-a51e-40b1-a49f-e04045480fd5
creation_date: '2023-04-11T15:30:39Z'
deletion_date: '2023-05-11T15:30:39Z'
customer_id: 160c0c4b-9966-4dc1-a916-8407eb10d74e
initiator_id: 06588898-9a84-4b35-ba8f-f9cbd64946f3
primary_applicant:
first_name: John
last_name: Doe
secondary_applicants:
- first_name: Jane
last_name: Doe
accounts_connected: 0
customer_link:
created_at: '2023-04-11T15:31:39Z'
url: https://path-to-customer-link/b5daa5f7-b993-42e9-a232-76057151bacf
finished_connecting_accounts: false
expired: false
status: requested
review_status: ''
review_date: '2023-05-11T15:30:39Z'
metadata:
loan_product_code: credit_card_1234
financial_data_consent: one_time
metadata:
timezone: Europe/London
date_range_end: latest_calendar_month
date_ranges:
- from: '2023-04-01T00:00:00+01:00'
to: '2023-04-31T23:59:59+01:00'
duration: P1M
- from: '2023-02-01T00:00:00Z'
to: '2023-04-31T23:59:59+01:00'
duration: P3M
- from: '2022-11-01T00:00:00Z'
to: '2023-04-31T23:59:59+01:00'
duration: P6M
- from: '2022-05-01T00:00:00+01:00'
to: '2023-04-31T23:59:59+01:00'
duration: P12M
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
delete:
tags:
- Customer Applications
summary: Delete Customer Application
description: |
Delete an individual customer's application, and all financial data
associated with it.
operationId: v1_customer_application_delete
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerApplicationID'
responses:
'204':
description: The request was successfully processed. No Content returned
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/assess/v1/customer-applications/{application_id}/customer-links:
post:
tags:
- Customer Application Links
summary: Retrieve Customer Application URL
description: |
Allow customers to share their account information in relation to a
specific application. A URL is provided in the response, which is to be
given to the customer for them to follow in order to share their
information.
If a valid email is specified in the request, Bud will automatically
send an email to the customer with the link embedded, and with
instructions for the customer to proceed.
This email will also override/set the `metadata.customer_email` property
on the customer application.
operationId: v1_customer_applications_customer_links_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerApplicationID'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PostCustomerLinksRequest'
example:
send_to: customer@example.com
redirect_url: https://your-domain.com/callback
callbacks:
Customer connected accounts:
'{$request.body#redirect_url}':
get:
summary: After customer attempts to connect accounts
security: []
description: |
Check the `status` query parameter before handling the redirection.
If `status` is `success`, then the customer successfully connected their accounts.
parameters:
- $ref: '#/components/parameters/RedirectURLCallbackStatus'
- $ref: '#/components/parameters/RedirectURLCallbackCustomerID'
- $ref: '#/components/parameters/RedirectURLCallbackTaskID'
- $ref: '#/components/parameters/RedirectURLCallbackApplicationID'
- $ref: '#/components/parameters/RedirectURLCallbackConnectionID'
- $ref: '#/components/parameters/RedirectURLCallbackError'
responses:
'200':
description: OK
content:
text/html:
schema: {}
responses:
'201':
description: The request was successfully processed.
content:
application/json:
schema:
$ref: '#/components/schemas/PostCustomerLinksResponse'
example:
operation_id: v1_customer_applications_customer_links_post
data:
link: https://url-to-customer-dashboard.thisisbud.com/connect-accounts/1674af1a-96ce-4517-97c4-6937592b0807
metadata:
connection_id: d3547de1-d1f2-4344-b4c2-17169b7526f9
'401':
description: An unauthenticated request was received.
'405':
description: The request uses an unexpected HTTP method.
5XX:
description: An unexpected error occurred on the server side.
/aggregations/v2/buckets:
post:
operationId: aggregations_v2_buckets_post
summary: Create Buckets
description: |
Create a new bucket, which can be used to group transactions for totals.
tags:
- Aggregation Buckets
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBucketRequest'
example:
name: example-bucket
categorisation_model: uk-v2
buckets:
- bucket_l1: housing_fuel_and_power
criteria:
- bucket_l2: mortgage_repayment
category_l1: mortgage_and_rent
category_l2: mortgage
- bucket_l2: rent_payment
category_l1: mortgage_and_rent
category_l2: rent
- bucket_l2: electricity_and_gas
category_l1: utilities
category_l2: utilities_energy
- bucket_l2: other_fuels
category_l1: utilities
category_l2: other_utilities
- bucket_l1: recreation_and_culture
criteria:
- bucket_l2: holiday
category_l1: travel
category_l2: holiday_and_travel_expenses
- bucket_l2: pet_care
category_l1: home
category_l2: pets
- bucket_l2: leisure_and_culture
category_l1: entertainment
category_l2: leisure_and_amusement_activities
- bucket_l2: reading
category_l1: entertainment
category_l2: books_and_reading
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBucketResponse'
example:
operation_id: aggregations_v2_buckets_post
data:
bucket_id: a95e911c-900a-437c-a91e-d31c09ffd3ce
'400':
description: Bad Request
'401':
description: Unauthorized
get:
summary: Retrieve All Buckets
description: |
Retrieve the top-level definitions of buckets you have created.
Use this to retrieve the IDs of buckets to then retrieve their individual
definitions and totals for customer transactions.
operationId: aggregations_v2_buckets_get
tags:
- Aggregation Buckets
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBucketsResponse'
example:
operation_id: aggregations_v2_buckets_get
data:
- bucket_id: a95e911c-900a-437c-a91e-d31c09ffd3ce
name: example-bucket
created_at: '2023-05-05T00:00:00Z'
updated_at: '2023-06-07T12:30:00Z'
categorisation_model: uk-v2
buckets:
- housing_fuel_and_power
- recreation_and_culture
- bucket_id: 3163323b-1894-4e85-8fca-010686ef132f
name: example-bucket-2
created_at: '2023-06-05T00:00:00Z'
updated_at: '2023-06-01T12:30:00Z'
categorisation_model: uk-v2
buckets:
- income
- fixed_expenditure
- flexible_expenditure
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
/aggregations/v2/buckets/{bucket_id}:
get:
summary: Retrieve Bucket
description: |
Retrieve the definition of a bucket, and retrieve helper metadata which can be used
for presenting options to customers.
For example, the `metadata.category_lookup` property can be used to show a dialog box
to customers for the customers to be able to correct their transactions (using the
[Correct Transaction Categories V2](https://docs.thisisbud.com/reference/corrections_v2_categories_post)),
and using the correct `category_l1/category_l2` pair.
operationId: aggregations_v2_bucket_get
tags:
- Aggregation Buckets
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/BucketID'
- $ref: '#/components/parameters/CategoryLookup'
- $ref: '#/components/parameters/BucketLookup'
- $ref: '#/components/parameters/UnbucketedCategories'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBucketResponse'
example:
operation_id: aggregations_v2_bucket_get
data:
bucket_id: a95e911c-900a-437c-a91e-d31c09ffd3ce
name: example-bucket
created_at: '2023-05-05T00:00:00Z'
updated_at: '2023-06-07T12:30:00Z'
categorisation_model: uk-v2
buckets:
- bucket_l1: housing_fuel_and_power
criteria:
- bucket_l2: mortgage_repayment
category_l1: mortgage_and_rent
category_l2: mortgage
- bucket_l2: rent_payment
category_l1: mortgage_and_rent
category_l2: rent
- bucket_l2: electricity_and_gas
category_l1: utilities
category_l2: utilities_energy
- bucket_l2: other_fuels
category_l1: utilities
category_l2: other_utilities
- bucket_l1: recreation_and_culture
criteria:
- bucket_l2: holiday
category_l1: travel
category_l2: holiday_and_travel_expenses
- bucket_l2: pet_care
category_l1: home
category_l2: pets
- bucket_l2: leisure_and_culture
category_l1: entertainment
category_l2: leisure_and_amusement_activities
- bucket_l2: reading
category_l1: entertainment
category_l2: books_and_reading
metadata:
category_lookup:
housing_fuel_and_power:
mortgage_repayment:
category_l1: mortgage_and_rent
category_l2: mortgage
rent_payment:
category_l1: mortgage_and_rent
category_l2: rent
electricity_and_gas:
category_l1: utilities
category_l2: utilities_energy
other_fuels:
category_l1: utilities
category_l2: other_utilities
recreation_and_culture:
holiday:
category_l1: travel
category_l2: holiday_and_travel_expenses
pet_care:
category_l1: home
category_l2: pets
leisure_and_culture:
category_l1: entertainment
category_l2: leisure_and_amusement_activities
reading:
category_l1: entertainment
category_l2: books_and_reading
bucket_lookup:
entertainment:
leisure_and_amusement_activities:
bucket_l1: recreation_and_culture
bucket_l2: leisure_and_culture
books_and_reading:
bucket_l1: recreation_and_culture
bucket_l2: reading
home:
pets:
bucket_l1: recreation_and_culture
bucket_l2: pet_care
travel:
holiday_and_travel_expenses:
bucket_l1: recreation_and_culture
bucket_l2: holiday
utilities:
utilities_energy:
bucket_l1: housing_fuel_and_power
bucket_l2: electricity_and_gas
other_utilities:
bucket_l1: housing_fuel_and_power
bucket_l2: other_fuels
mortgage_and_rent:
mortgage:
bucket_l1: housing_fuel_and_power
bucket_l2: mortgage_repayment
rent:
bucket_l1: housing_fuel_and_power
bucket_l2: rent_payment
unbucketed_categories:
- category_l1: education
category_l2: driving_lessons
- category_l1: utilities
category_l2: waste_and_recycling
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestNotFoundResponse'
example:
operation_id: aggregations_v2_bucket_get
code_id: not_found
message: bucket not found
put:
operationId: aggregations_v2_bucket_put
summary: Update Bucket
description: |
Update an existing bucket (overwrites all content).
tags:
- Aggregation Buckets
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/BucketID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBucketRequest'
example:
name: example-bucket-updated
categorisation_model: uk-v2
buckets:
- bucket_l1: housing_fuel_and_power
additional_data:
display_name: Housing, fuel & power
criteria:
- bucket_l2: mortgage_repayment
category_l1: mortgage_and_rent
category_l2: mortgage
additional_data:
display_name: Mortgage repayment
- bucket_l2: rent_payment
category_l1: mortgage_and_rent
additional_data:
display_name: Rent repayment
category_l2: rent
- bucket_l2: electricity_and_gas
category_l1: utilities
category_l2: utilities_energy
additional_data:
display_name: Electricity & gas
- bucket_l2: other_fuels
category_l1: utilities
category_l2: other_utilities
additional_data:
display_name: Other fuels
- bucket_l1: recreation_and_culture
additional_data:
display_name: Recreation & Culture
criteria:
- bucket_l2: holiday
category_l1: travel
category_l2: holiday_and_travel_expenses
additional_data:
display_name: Holiday
- bucket_l2: pet_care
category_l1: home
category_l2: pets
additional_data:
display_name: Pet care
- bucket_l2: leisure_and_culture
category_l1: entertainment
category_l2: leisure_and_amusement_activities
additional_data:
display_name: Leisure & culture
- bucket_l2: reading
category_l1: entertainment
category_l2: books_and_reading
additional_data:
display_name: Reading
responses:
'204':
description: No Content
'400':
description: Bad Request
'401':
description: Unauthorized
delete:
summary: Delete Buckets
operationId: aggregations_v2_bucket_delete
tags:
- Aggregation Buckets
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/BucketID'
responses:
'204':
description: No Content
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Bucket not found
/aggregations/v2/buckets/{bucket_id}/totals:
get:
summary: Retrieve Bucket Totals
description: |
Retrieve the totals of a defined bucket for a particular customer.
Use the `group_by` property to configure how the totals are grouped together
(e.g. by `bucket_l1`, by `month`, etc...)
operationId: aggregations_v2_bucket_totals_get
tags:
- Aggregation Buckets
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/BucketID'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/DateFrom'
- $ref: '#/components/parameters/DateTo'
- $ref: '#/components/parameters/QueryCurrency'
- $ref: '#/components/parameters/Timezone'
- $ref: '#/components/parameters/GroupBy'
- $ref: '#/components/parameters/DeprecatedURLMonthFrom'
- $ref: '#/components/parameters/DeprecatedURLMonthTo'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBucketTotalsResponse'
examples:
Group By bucket_l1:
value:
operation_id: aggregations_v2_bucket_totals_get
data:
- group_name: housing_fuel_and_power
group_type: bucket_l1
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power/transactions/incoming
outgoing:
total:
value: '6000.00'
currency: GBP
monthly_average:
value: '2000.00'
currency: GBP
transaction_count: 3
_links:
transactions: /path/to/housing_fuel_and_power/transactions/outgoing
transaction_count: 3
_links:
transactions: /path/to/housing_fuel_and_power/transactions
- group_name: recreation_and_culture
group_type: bucket_l1
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture/transactions/incoming
outgoing:
total:
value: '9000.00'
currency: GBP
monthly_average:
value: '3000.00'
currency: GBP
transaction_count: 3
_links:
transactions: /path/to/recreation_and_culture/transactions/outgoing
transaction_count: 3
_links:
transactions: /path/to/recreation_and_culture/transactions
metadata:
date_from: '2023-01-01T00:00:00Z'
date_to: '2023-03-31T23:59:59Z'
group_by:
- bucket_l1
currency: GBP
Group By bucket_l1 then bucket_l2:
value:
operation_id: aggregations_v2_bucket_totals_get
data:
- group_name: housing_fuel_and_power
group_type: bucket_l1
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power/transactions/incoming
outgoing:
total:
value: '6000.00'
currency: GBP
monthly_average:
value: '2000.00'
currency: GBP
transaction_count: 3
_links:
transactions: /path/to/housing_fuel_and_power/transactions/outgoing
transaction_count: 3
_links:
transactions: /path/to/housing_fuel_and_power/transactions
subtotals:
- group_name: mortgage_repayment
group_type: bucket_l2
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_mortgage_repayment/transactions/incoming
outgoing:
total:
value: '6000.00'
currency: GBP
monthly_average:
value: '2000.00'
currency: GBP
transaction_count: 3
_links:
transactions: /path/to/housing_fuel_and_power_mortgage_repayment/transactions/outgoing
transaction_count: 3
_links:
transactions: /path/to/housing_fuel_and_power_mortgage_repayment/transactions
- group_name: rent_payment
group_type: bucket_l2
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_rent_payment/transactions/incoming
outgoing:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_rent_payment/transactions/outgoing
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_rent_payment/transactions
- group_name: electricity_and_gas
group_type: bucket_l2
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_electricity_and_gas/transactions/incoming
outgoing:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_electricity_and_gas/transactions/outgoing
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_electricity_and_gas/transactions
- group_name: other_fuels
group_type: bucket_l2
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_other_fuels/transactions/incoming
outgoing:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_other_fuels/transactions/outgoing
transaction_count: 0
_links:
transactions: /path/to/housing_fuel_and_power_other_fuels/transactions
- group_name: recreation_and_culture
group_type: bucket_l1
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture/transactions/incoming
outgoing:
total:
value: '9000.00'
currency: GBP
monthly_average:
value: '3000.00'
currency: GBP
transaction_count: 3
_links:
transactions: /path/to/recreation_and_culture/transactions/outgoing
transaction_count: 3
_links:
transactions: /path/to/recreation_and_culture/transactions
subtotals:
- group_name: holiday
group_type: bucket_l2
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_holiday/transactions/incoming
outgoing:
total:
value: '9000.00'
currency: GBP
monthly_average:
value: '3000.00'
currency: GBP
transaction_count: 3
_links:
transactions: /path/to/recreation_and_culture_holiday/transactions/outgoing
transaction_count: 3
_links:
transactions: /path/to/recreation_and_culture_holiday/transactions
- group_name: holiday
group_type: bucket_l2
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_pet_care/transactions/incoming
outgoing:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_pet_care/transactions/outgoing
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_pet_care/transactions
- group_name: leisure_and_culture
group_type: bucket_l2
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_leisure_and_culture/transactions/incoming
outgoing:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_leisure_and_culture/transactions/outgoing
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_leisure_and_culture/transactions
- group_name: reading
group_type: bucket_l2
incoming:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_reading/transactions/incoming
outgoing:
total:
value: '0.00'
currency: GBP
monthly_average:
value: '0.00'
currency: GBP
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_reading/transactions/outgoing
transaction_count: 0
_links:
transactions: /path/to/recreation_and_culture_reading/transactions
metadata:
date_from: '2023-01-01T00:00:00Z'
date_to: '2023-03-31T23:59:59Z'
group_by:
- bucket_l1
- bucket_l2
currency: GBP
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Bucket not found
/affordability/v2/report:
get:
tags:
- Retrieve Affordability Report V2
summary: Retrieve Affordability Report V2
description: Get an overview of a customer's financial status.
operationId: v2_affordability_report
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/URLMonthFrom'
- $ref: '#/components/parameters/URLMonthTo'
- $ref: '#/components/parameters/Timezone'
- $ref: '#/components/parameters/OverallTotals'
- $ref: '#/components/parameters/MonthlyTotals'
- in: query
name: currency
schema:
type: string
description: Currency code for relevant transactions (default `GBP`).
responses:
'200':
description: The request was successfully processed
content:
application/json:
schema:
$ref: '#/components/schemas/V2AffordabilityReportResponse'
examples:
Income and expenditure:
value:
operation_id: v2_affordability_report
data:
months_assessed:
start: 2022-01
end: 2022-03
accounts:
connected: 3
holder_names:
- John Doe
missing_data:
income: false
expenditure: false
assessment:
income:
net_disposable:
predicted_monthly:
value: '1500.00'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=net_disposable_income
net_discretionary:
predicted_monthly:
value: '70.00'
currency: GBP
_links:
income_transactions: /affordability/v2/transactions?criteria=net_disposable_income
expenditure_transactions: /affordability/v2/transactions?criteria=essential_expenditure
expenditure:
fixed:
predicted_monthly:
value: '1000.00'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=fixed_expenditure
flexible:
predicted_monthly_range:
low:
value: '10.00'
currency: GBP
high:
value: '100.00'
currency: GBP
average:
value: '56.00'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=flexible_expenditure
essential:
predicted_monthly:
value: '500.00'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=essential_expenditure
non_essential:
predicted_monthly:
value: '80.00'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=non_essential_expenditure
Overall and monthly totals included:
value:
operation_id: v2_affordability_report
data:
months_assessed:
start: 2023-01
end: 2023-06
accounts:
connected: 1
holder_names: []
missing_data:
income: false
expenditure: false
assessment:
income:
net_disposable:
overall_total:
value: '13800.00'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '2300.00'
currency: GBP
- month: 2023-02
amount:
value: '2300.00'
currency: GBP
- month: 2023-03
amount:
value: '2300.00'
currency: GBP
- month: 2023-04
amount:
value: '2300.00'
currency: GBP
- month: 2023-05
amount:
value: '2300.00'
currency: GBP
- month: 2023-06
amount:
value: '2300.00'
currency: GBP
predicted_monthly:
value: '2300.00'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=net_disposable_income&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
net_discretionary:
overall_total:
value: '-9.00'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '12.00'
currency: GBP
- month: 2023-02
amount:
value: '12.00'
currency: GBP
- month: 2023-03
amount:
value: '-69.00'
currency: GBP
- month: 2023-04
amount:
value: '12.00'
currency: GBP
- month: 2023-05
amount:
value: '12.00'
currency: GBP
- month: 2023-06
amount:
value: '12.00'
currency: GBP
predicted_monthly:
value: '-1.50'
currency: GBP
_links:
income_transactions: /affordability/v2/transactions?criteria=net_disposable_income&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
expenditure_transactions: /affordability/v2/transactions?criteria=essential_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
expenditure:
essential:
overall_total:
value: '13809.00'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '2288.00'
currency: GBP
- month: 2023-02
amount:
value: '2288.00'
currency: GBP
- month: 2023-03
amount:
value: '2369.00'
currency: GBP
- month: 2023-04
amount:
value: '2288.00'
currency: GBP
- month: 2023-05
amount:
value: '2288.00'
currency: GBP
- month: 2023-06
amount:
value: '2288.00'
currency: GBP
predicted_monthly:
value: '2301.50'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=essential_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
non_essential:
overall_total:
value: '4232.44'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '1198.52'
currency: GBP
- month: 2023-02
amount:
value: '591.20'
currency: GBP
- month: 2023-03
amount:
value: '747.84'
currency: GBP
- month: 2023-04
amount:
value: '534.80'
currency: GBP
- month: 2023-05
amount:
value: '597.20'
currency: GBP
- month: 2023-06
amount:
value: '562.88'
currency: GBP
predicted_monthly:
value: '705.41'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=non_essential_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
fixed:
overall_total:
value: '12466.08'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '2024.00'
currency: GBP
- month: 2023-02
amount:
value: '2104.08'
currency: GBP
- month: 2023-03
amount:
value: '2102.32'
currency: GBP
- month: 2023-04
amount:
value: '2062.96'
currency: GBP
- month: 2023-05
amount:
value: '2108.96'
currency: GBP
- month: 2023-06
amount:
value: '2063.76'
currency: GBP
predicted_monthly:
value: '2077.68'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=fixed_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
flexible:
overall_total:
value: '5575.36'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '1462.52'
currency: GBP
- month: 2023-02
amount:
value: '775.12'
currency: GBP
- month: 2023-03
amount:
value: '1014.52'
currency: GBP
- month: 2023-04
amount:
value: '759.84'
currency: GBP
- month: 2023-05
amount:
value: '776.24'
currency: GBP
- month: 2023-06
amount:
value: '787.12'
currency: GBP
predicted_monthly_range:
low:
value: '759.84'
currency: GBP
high:
value: '1462.52'
currency: GBP
average:
value: '929.23'
currency: GBP
_links:
transactions: /affordability/v2/transactions?criteria=flexible_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
'400':
description: The request contains an invalid payload.
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/affordability/report:
get:
tags:
- Retrieve Affordability Report
summary: Retrieve Affordability Report
description: |
Get an overview of a customer's financial status.
> ❗️ Deprecation:
>
> Support will cease for this endpoint on the 31st of August 2025 - please complete your migration to the Retrieve Affordability Report V2 endpoint by that point in time.
> For further details, contact your Bud account manager or email help@thisisbud.com.
deprecated: true
operationId: v1_affordability_report
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/URLMonthFrom'
- $ref: '#/components/parameters/URLMonthTo'
- $ref: '#/components/parameters/Timezone'
- $ref: '#/components/parameters/OverallTotals'
- $ref: '#/components/parameters/MonthlyTotals'
- in: query
name: currency
schema:
type: string
description: Currency code for relevant transactions (default `GBP`).
responses:
'200':
description: The request was successfully processed
content:
application/json:
schema:
$ref: '#/components/schemas/AffordabilityReportResponse'
examples:
Income and expenditure:
value:
operation_id: v1_affordability_report
data:
months_assessed:
start: 2022-01
end: 2022-03
accounts:
connected: 3
holder_names:
- John Doe
missing_data:
income: false
expenditure: false
assessment:
income:
net_disposable:
predicted_monthly:
value: '1500.00'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=net_disposable_income
net_discretionary:
predicted_monthly:
value: '70.00'
currency: GBP
_links:
income_transactions: /v1/affordability/transactions?criteria=net_disposable_income
expenditure_transactions: /v1/affordability/transactions?criteria=essential_expenditure
expenditure:
fixed:
predicted_monthly:
value: '1000.00'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=fixed_expenditure
flexible:
predicted_monthly_range:
low:
value: '10.00'
currency: GBP
high:
value: '100.00'
currency: GBP
average:
value: '56.00'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=flexible_expenditure
essential:
predicted_monthly:
value: '500.00'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=essential_expenditure
non_essential:
predicted_monthly:
value: '80.00'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=non_essential_expenditure
Overall and monthly totals included:
value:
operation_id: v1_affordability_report
data:
months_assessed:
start: 2023-01
end: 2023-06
accounts:
connected: 1
holder_names: []
missing_data:
income: false
expenditure: false
assessment:
income:
net_disposable:
overall_total:
value: '13800.00'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '2300.00'
currency: GBP
- month: 2023-02
amount:
value: '2300.00'
currency: GBP
- month: 2023-03
amount:
value: '2300.00'
currency: GBP
- month: 2023-04
amount:
value: '2300.00'
currency: GBP
- month: 2023-05
amount:
value: '2300.00'
currency: GBP
- month: 2023-06
amount:
value: '2300.00'
currency: GBP
predicted_monthly:
value: '2300.00'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=net_disposable_income&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
net_discretionary:
overall_total:
value: '-9.00'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '12.00'
currency: GBP
- month: 2023-02
amount:
value: '12.00'
currency: GBP
- month: 2023-03
amount:
value: '-69.00'
currency: GBP
- month: 2023-04
amount:
value: '12.00'
currency: GBP
- month: 2023-05
amount:
value: '12.00'
currency: GBP
- month: 2023-06
amount:
value: '12.00'
currency: GBP
predicted_monthly:
value: '-1.50'
currency: GBP
_links:
income_transactions: /v1/affordability/transactions?criteria=net_disposable_income&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
expenditure_transactions: /v1/affordability/transactions?criteria=essential_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
expenditure:
essential:
overall_total:
value: '13809.00'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '2288.00'
currency: GBP
- month: 2023-02
amount:
value: '2288.00'
currency: GBP
- month: 2023-03
amount:
value: '2369.00'
currency: GBP
- month: 2023-04
amount:
value: '2288.00'
currency: GBP
- month: 2023-05
amount:
value: '2288.00'
currency: GBP
- month: 2023-06
amount:
value: '2288.00'
currency: GBP
predicted_monthly:
value: '2301.50'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=essential_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
non_essential:
overall_total:
value: '4232.44'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '1198.52'
currency: GBP
- month: 2023-02
amount:
value: '591.20'
currency: GBP
- month: 2023-03
amount:
value: '747.84'
currency: GBP
- month: 2023-04
amount:
value: '534.80'
currency: GBP
- month: 2023-05
amount:
value: '597.20'
currency: GBP
- month: 2023-06
amount:
value: '562.88'
currency: GBP
predicted_monthly:
value: '705.41'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=non_essential_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
fixed:
overall_total:
value: '12466.08'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '2024.00'
currency: GBP
- month: 2023-02
amount:
value: '2104.08'
currency: GBP
- month: 2023-03
amount:
value: '2102.32'
currency: GBP
- month: 2023-04
amount:
value: '2062.96'
currency: GBP
- month: 2023-05
amount:
value: '2108.96'
currency: GBP
- month: 2023-06
amount:
value: '2063.76'
currency: GBP
predicted_monthly:
value: '2077.68'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=fixed_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
flexible:
overall_total:
value: '5575.36'
currency: GBP
monthly_totals:
- month: 2023-01
amount:
value: '1462.52'
currency: GBP
- month: 2023-02
amount:
value: '775.12'
currency: GBP
- month: 2023-03
amount:
value: '1014.52'
currency: GBP
- month: 2023-04
amount:
value: '759.84'
currency: GBP
- month: 2023-05
amount:
value: '776.24'
currency: GBP
- month: 2023-06
amount:
value: '787.12'
currency: GBP
predicted_monthly_range:
low:
value: '759.84'
currency: GBP
high:
value: '1462.52'
currency: GBP
average:
value: '929.23'
currency: GBP
_links:
transactions: /v1/affordability/transactions?criteria=flexible_expenditure&date_from=2023-01-01T00:00:00Z&date_to=2023-06-30T23:59:59+01:00¤cy=GBP
'400':
description: The request contains an invalid payload.
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/affordability/transactions:
get:
tags:
- Retrieve Affordability Report
summary: Retrieve Affordability Transactions
description: |
View the transactions that were used to calculate a customer's Retrieve Affordability Report.
> ❗️ Deprecation:
>
> Support will cease for this endpoint on the 31st of Jan 2025 - please complete your migration to the Retrieve Affordability Transactions V2 endpoint by that point in time. For further details, contact your Bud account manager or email help@thisisbud.com.
operationId: v1_affordability_transactions_get
deprecated: true
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/DateFrom'
- $ref: '#/components/parameters/DateTo'
- $ref: '#/components/parameters/Criteria'
responses:
'200':
description: The request was successfully processed
content:
application/json:
schema:
$ref: '#/components/schemas/SpendingGroupsTransactionsResponse'
example:
operation_id: v1_affordability_transactions_get
data:
- transaction_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
account_id: fdcc55c6-f347-4abc-8c66-61ff290d8bd4
description: Bud
date: '2012-05-30'
indicator: Credit
amount:
amount: '1500.00'
currency: GBP
categories:
l1: finances
l2: income
criteria_satisfied:
- net_disposable_income
'400':
description: The request contains an invalid payload.
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/affordability/v2/transactions:
get:
tags:
- Retrieve Affordability Report V2
summary: Retrieve Affordability Transactions V2
description: |
This is a complimentary endpoint to the Retrieve Affordability Report V2 endpoint. This endpoint
is designed to allow clients to retrieve transactions used to generate sections of the V2 affordability report.
Transactions returned via this endpoint are filtered based on the criteria provided in the request, and
resemble the V2 transaction response format found in the v2_transactions_get endpoint.
operationId: v2_affordability_transactions_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/DateFrom'
- $ref: '#/components/parameters/DateTo'
- $ref: '#/components/parameters/Criteria'
responses:
'200':
description: The request was successfully processed
content:
application/json:
schema:
$ref: '#/components/schemas/AffordabilityTransactionResponse'
example:
operation_id: v2_affordability_transactions_get
data:
- transaction_id: da4ad499c86956e65e811fc88f6b54af
account_id: 72fa858459bd32ce0b5fd9daf813fd07
provider: BankOfBud
description: PayPal Transfer John Doe
credit_debit_indicator: credit
status: pending
suggested_description: john doe
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/a3af57fc-ec8a-4258-a8da-8d34f11640f6/v2/paypal.jpeg
amount:
value: '10.99'
currency: GBP
date_time: '2022-01-02T15:00:00Z'
metadata:
results: 1
'400':
description: The request contains an invalid payload.
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/insights/beta/report/income-expenditure:
get:
tags:
- Retrieve Affordability Risk Insights
summary: Retrieve income/expenditure break down reports
security:
- OAuth2: []
description: |
Retrieve income/expenditure break down reports. Each report is presented as a total expenditure vs income break
down to give a high level overview of a customers spending's in comparison to income.
For transactional analysis of particular aggregate, please refer to the transactions reference found within the
`_links` properties.
operationId: insights_beta_report_income_expenditure_get
parameters:
- $ref: '#/components/parameters/EnabledInsightsIncomeExpenditure'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Currency'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IncomeExpenditureReportResponse'
example:
operation_id: insights_beta_report_income_expenditure_get
data:
insights:
- type: income-loan
currency: GBP
expenditure:
credit_debit_indicator: debit
count: 10
total:
value: '1000.00'
currency: GBP
monthly_average:
value: '250.00'
currency: GBP
breakdown:
- from: '2024-01-17T00:00:00+08:00'
to: '2024-02-16T23:59:59+08:00'
total:
value: '250.00'
currency: GBP
count: 1
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
- from: '2024-02-17T00:00:00+08:00'
to: '2024-03-16T23:59:59+08:00'
total:
value: '250.00'
currency: GBP
count: 1
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
- from: '2024-04-17T00:00:00+08:00'
to: '2024-05-16T23:59:59+08:00'
total:
value: '250.00'
currency: GBP
average:
value: '250.00'
currency: GBP
count: 1
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
relative_to_income: '1'
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
income:
credit_debit_indicator: credit
count: 4
total:
value: '1000.00'
currency: GBP
monthly_average:
value: '250.00'
currency: GBP
breakdown:
- from: '2024-01-17T00:00:00+08:00'
to: '2024-02-16T23:59:59+08:00'
total:
value: '250.00'
currency: GBP
count: 1
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
- from: '2024-02-17T00:00:00+08:00'
to: '2024-03-16T23:59:59+08:00'
total:
value: '250.00'
currency: GBP
count: 1
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
- from: '2024-03-17T00:00:00+08:00'
to: '2024-04-16T23:59:59+08:00'
total:
value: '250.00'
currency: GBP
average:
value: '250.00'
currency: GBP
count: 1
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
metadata:
from: '2022-01-01T00:00:00Z'
to: '2022-03-31T00:00:00Z'
currencies:
- GBP
options:
- insight_type: late_income
option: minimum_days_late_threshold
value: '3'
- insight_type: late_income
option: minimum_value_threshold
value: '100.00'
/insights/beta/report/income-expenditure/transactions/{reference}:
get:
tags:
- Retrieve Affordability Risk Insights
summary: Retrieve transactions relating to a specific insight report section.
security:
- OAuth2: []
description: |
Each report, where appropriate will have a unique reference for that specific aggregated section of the report.
using the same parameters used in the call to `insights_beta_report_income_expenditure_get`,
in combination with the unique reference, will return the raw transactions
list used to produce that aggregation. This is useful if requiring further investigation or analysis.
The reference can be found in the `_links` section of the insight reports.
NOTE:
Alterations to the `to`/`from` query properties will result in an alternative dataset being returned.
operationId: insights_beta_report_income_expenditure_transactions_get
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Currency'
- $ref: '#/components/parameters/TransactionReference'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReportInsightsTransactionResponse'
example:
operation_id: insights_beta_report_income_expenditure_transactions_get
data:
- transaction_id: a_transaction_id
account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
provider: a_bank_account_provider
description: SALARY
credit_debit_indicator: credit
status: booked
suggested_description: salary
amount:
value: '3000.00'
currency: GBP
date_time: '2023-04-10T10:00:00Z'
enrichments:
categories:
l1:
slug: income
confidence: '0.99'
l2:
slug: employment_income
confidence: '0.98'
regularity:
slug: monthly
confidence: '0.99'
predicted_date_times:
- '2023-05-10T10:00:00Z'
metadata:
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
from: '2020-01-01T00:00:00Z'
to: '2020-01-31T00:00:00Z'
currencies:
- GBP
options:
- insight_type: late_income
option: minimum_days_late_threshold
value: '3'
- insight_type: late_income
option: minimum_value_threshold
value: '100.00'
/insights/beta/report/merchants:
get:
tags:
- Retrieve Affordability Risk Insights
summary: Retrieve merchant-specific breakdown reports.
security:
- OAuth2: []
description: |
Endpoint is responsible for returning merchant based aggregated transaction breakdowns. The reports are presented in
a way that allows for a high level overview of a customers spending habits with specific merchants.
For transactional analysis of particular aggregate, please refer to the transactions reference found within the
`_links` properties.
operationId: insights_beta_report_merchants_get
parameters:
- $ref: '#/components/parameters/EnabledInsightsMerchants'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Currency'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MerchantsReportResponse'
example:
operation_id: insights_beta_report_merchants_get
data:
insights:
hcst_credit:
- type: hcst-credit
currency: GBP
transactions_count: 2
merchants_count: 2
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions?category_l1=bills&category_l2=tv_and_broadband&date_from=2022-01-01T00%3A00%3A00Z&date_to=2022-03-31T00%3A00%3A00Z
metadata:
from: '2022-01-01T00:00:00Z'
to: '2022-03-31T00:00:00Z'
currencies:
- GBP
options: []
/insights/beta/report/merchants/transactions/{reference}:
get:
tags:
- Retrieve Affordability Risk Insights
security:
- OAuth2: []
summary: Retrieve transactions relating to a specific insight report section.
description: |
Each report, where appropriate will have a unique reference for that specific aggregated section of the report.
using the same parameters used in the call to `insights_beta_report_merchants_get`,
in combination with the unique reference, will return the raw transactions
list used to produce that aggregation. This is useful if requiring further investigation or analysis.
The reference can be found in the `_links` section of the insight reports.
NOTE:
Alterations to the `to`/`from` query properties will result in an alternative dataset being returned.
operationId: insights_beta_report_merchants_transactions_get
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Currency'
- $ref: '#/components/parameters/TransactionReference'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReportInsightsTransactionResponse'
example:
operation_id: insights_beta_report_merchants_transactions_get
data:
- transaction_id: a_transaction_id
account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
provider: a_bank_account_provider
description: SALARY
credit_debit_indicator: credit
status: booked
suggested_description: salary
amount:
value: '3000.00'
currency: GBP
date_time: '2023-04-10T10:00:00Z'
enrichments:
categories:
l1:
slug: income
confidence: '0.99'
l2:
slug: employment_income
confidence: '0.98'
regularity:
slug: monthly
confidence: '0.99'
predicted_date_times:
- '2023-05-10T10:00:00Z'
metadata:
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
from: '2020-01-01T00:00:00Z'
to: '2020-01-31T00:00:00Z'
options: []
/insights/beta/report/balance/unauthorised-overdraft:
get:
tags:
- Retrieve Affordability Risk Insights
security:
- OAuth2: []
summary: Retrieve a report on a customers unauthorised overdraft.
description: |
Endpoint is responsible for returning balance based aggregated transaction breakdowns and insights.
The reports are presented in a way that allows for a high level overview of a customers balances.
This particular route focuses on customer accounts with unauthorised overdrafts.
For transactional analysis of particular aggregate, please refer to the transactions reference found within the
`_links` properties.
operationId: insights_beta_report_balance_unauthorised_overdraft_get
parameters:
- $ref: '#/components/parameters/EnabledInsightsBalanceOverdraft'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Currency'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorisedOverdraftResponse'
examples:
unauthorised_overdraft_detected:
summary: Unauthorised overdraft detected
description: |
a simple example where a customers account has been noted to have been in an unauthorised overdraft
value:
operation_id: insights_beta_report_balance_unauthorised_overdraft_get
data:
insights:
- type: unauthorised-overdraft
currency: GBP
days_in_unauthorised_overdraft:
count: 3
ratio: '0.06'
accounts:
- account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
provider: test provider
account_name: current account
days_in_unauthorised_overdraft:
count: 3
ratio: '0.06'
unauthorised_overdraft_occurrences:
- date: '2023-03-20T00:00:00Z'
amount:
value: '1200.00'
currency: GBP
credit_debit_indicator: debit
- date: '2023-03-21T00:00:00Z'
amount:
value: '1200.00'
currency: GBP
credit_debit_indicator: debit
- date: '2023-03-22T00:00:00Z'
amount:
value: '1200.00'
currency: GBP
credit_debit_indicator: debit
balances:
- date: '2023-01-12T00:00:00Z'
amount:
value: '100.00'
currency: GBP
type: closing_available
credit_debit_indicator: debit
credit_lines:
- date: '2023-01-12T00:00:00Z'
type: available
amount:
value: '850.00'
currency: GBP
transactions_reference: 123419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
metadata:
from: '2020-01-01T00:00:00Z'
to: '2020-01-31T00:00:00Z'
currencies:
- GBP
options: []
no_unauthorised_overdrafts_detected_in_accounts:
summary: No unauthorised access to overdraft detected
description: |
for a given to/from period, no days have been detected as being in overdraft for accounts currently ingested.
An insight will be returned per currency detected from ingested accounts.
value:
operation_id: insights_beta_report_balance_unauthorised_overdraft_get
data:
insights:
- type: unauthorised-overdraft
currency: GBP
days_in_unauthorised_overdraft:
count: 0
ratio: '0.00'
accounts: []
metadata:
from: '2020-01-01T00:00:00Z'
to: '2020-01-31T00:00:00Z'
currencies:
- GBP
options: []
no_ingested_data_response:
summary: No data ingested
description: |
In the event a client requests a report for a customer that has no ingested data,
a response will be returned with no insights available. We do this because we cannot guarantee the
currency of the customers accounts, and therefore cannot return a report with no currency.
value:
operation_id: insights_beta_report_balance_unauthorised_overdraft_get
data:
insights: []
metadata:
from: '2020-01-01T00:00:00Z'
to: '2020-01-31T00:00:00Z'
currencies: []
options: []
/insights/beta/report/balance/unauthorised-overdraft/transactions/{reference}:
get:
tags:
- Retrieve Affordability Risk Insights
security:
- OAuth2: []
summary: Retrieve transactions relating to a specific insight report section.
description: |
Each report, where appropriate will have a unique reference for that specific aggregated section of the report.
using the same parameters used in the call to `insights_beta_report_balance_unauthorised_overdraft_get`,
in combination with the unique reference, will return the raw transactions
list used to produce that aggregation. This is useful if requiring further investigation or analysis.
The reference can be found in the `_links` section of the insight reports.
NOTE:
Alterations to the `to`/`from` query properties will result in an alternative dataset being returned.
operationId: insights_beta_report_unauthorised_overdraft_transactions_get
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Currency'
- $ref: '#/components/parameters/TransactionReference'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReportInsightsTransactionResponse'
example:
operation_id: insights_beta_report_unauthorised_overdraft_transactions_get
data:
- transaction_id: a_transaction_id
account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
provider: a_bank_account_provider
description: SALARY
credit_debit_indicator: credit
status: booked
suggested_description: salary
amount:
value: '3000.00'
currency: GBP
date_time: '2023-04-10T10:00:00Z'
enrichments:
categories:
l1:
slug: income
confidence: '0.99'
l2:
slug: employment_income
confidence: '0.98'
regularity:
slug: monthly
confidence: '0.99'
predicted_date_times:
- '2023-05-10T10:00:00Z'
metadata:
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
from: '2020-01-01T00:00:00Z'
to: '2020-01-31T00:00:00Z'
options:
- insight_type: late_income
option: minimum_days_late_threshold
value: '3'
- insight_type: late_income
option: minimum_value_threshold
value: '100.00'
/insights/beta/report/income-health:
get:
tags:
- Retrieve Affordability Risk Insights
security:
- OAuth2: []
summary: Retrieve a health report on a customers financial profile.
description: |
Retrieve a list of insights that reflect various health reports based on a customers ingested data.
Reports found within this grouping reflect aggregations against a customers income sources.
Where feasible, deep aggregate analysis is provided to allow for further insight.
For transactional analysis of particular aggregate, please refer to the transactions reference found within the
`_links` properties.
operationId: insights_beta_report_income_health_get
parameters:
- $ref: '#/components/parameters/EnabledInsightsIncomeHealth'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Currency'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IncomeHealthReportResponse'
example:
operation_id: insights_beta_report_income_health_get
data:
insights:
- type: income-health
currency: GBP
total:
value: '1500'
currency: GBP
monthly_average:
value: '1500'
currency: GBP
stability:
value: '0.8'
currency: GBP
regular_income:
stability:
value: '0.8'
currency: GBP
total:
value: '1500'
currency: GBP
monthly_average:
value: '1500'
currency: GBP
sources:
- source_name: customer employer salary
category_l1: income
category_l2: salary
group_id: F30F99BC-3532-44E8-B276-A55B2B026684
frequency: monthly
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
monthly_average:
value: '1500'
currency: GBP
total:
value: '1500'
currency: GBP
stability:
value: '0.8'
currency: GBP
transactions_reference: 123419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
irregular_income:
total:
value: '1500'
currency: GBP
monthly_average:
value: '1500'
currency: GBP
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
transactions_reference: 456419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
transactions_reference: 789419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
- type: income-health
currency: EUR
total:
value: '1730.06'
currency: EUR
monthly_average:
value: '1730.06'
currency: EUR
stability:
value: '0.8'
currency: EUR
regular_income:
stability:
value: '0.81'
currency: EUR
total:
value: '1730.06'
currency: EUR
monthly_average:
value: '1730.06'
currency: EUR
sources:
- source_name: customer employer salary
category_l1: income
category_l2: salary
group_id: F30F99BC-3532-44E8-B276-A55B2B026684
frequency: monthly
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
monthly_average:
value: '1500'
currency: GBP
total:
value: '1500'
currency: GBP
stability:
value: '0.8'
currency: GBP
- source_name: Bank Interest
category_l1: income
category_l2: interest_or_investments
group_id: F30F99BC-3532-44E8-B276-A55B2B026684
frequency: monthly
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
monthly_average:
value: '10'
currency: GBP
total:
value: '10'
currency: GBP
stability:
value: '1'
currency: GBP
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
irregular_income:
total:
value: '1500'
currency: EUR
monthly_average:
value: '1500'
currency: EUR
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
_links:
transactions: https://api-sandbox.thisisbud.com/financial/v2/transactions
metadata:
from: '2020-01-01T00:00:00Z'
to: '2020-01-31T00:00:00Z'
currencies:
- GBP
options:
- insight_type: late_income
option: minimum_days_late_threshold
value: '3'
- insight_type: late_income
option: minimum_value_threshold
value: '100.00'
/insights/beta/report/income-health/transactions/{reference}:
get:
tags:
- Retrieve Affordability Risk Insights
security:
- OAuth2: []
summary: Retrieve transactions relating to a specific insight report section.
description: |
Each report, where appropriate will have a unique reference for that specific aggregated section of the report.
using the same parameters used in the call to `insights_beta_report_balance_unauthorised_overdraft_get`,
in combination with the unique reference, will return the raw transactions
list used to produce that aggregation. This is useful if requiring further investigation or analysis.
The reference can be found in the `_links` section of the insight reports.
NOTE:
Alterations to the `to`/`from` query properties will result in an alternative dataset being returned.
operationId: insights_beta_report_income_health_transactions_get
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Currency'
- $ref: '#/components/parameters/TransactionReference'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReportInsightsTransactionResponse'
example:
operation_id: insights_beta_report_income_health_transactions_get
data:
- transaction_id: a_transaction_id
account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
provider: a_bank_account_provider
description: SALARY
credit_debit_indicator: credit
status: booked
suggested_description: salary
amount:
value: '3000.00'
currency: GBP
date_time: '2023-04-10T10:00:00Z'
enrichments:
categories:
l1:
slug: income
confidence: '0.99'
l2:
slug: employment_income
confidence: '0.98'
regularity:
slug: monthly
confidence: '0.99'
predicted_date_times:
- '2023-05-10T10:00:00Z'
metadata:
transactions_reference: 402419e92096bd4ab499de51bffcdcacb13eeb4b6452b327a334799ffd9f4df5
from: '2020-01-01T00:00:00Z'
to: '2020-01-31T00:00:00Z'
options:
- insight_type: late_income
option: minimum_days_late_threshold
value: '3'
- insight_type: late_income
option: minimum_value_threshold
value: '100.00'
/v1/payments/providers:
get:
tags:
- Initiate Payment - Bud license
- Initiate Payment - Client license
summary: Retrieve Providers
description: This endpoint is used list the payment service providers (PSPs) supported via Bud's Payment APIs.
operationId: v1_payments_providers_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/PaymentProviderRegionFilter'
- $ref: '#/components/parameters/PaymentProviderServiceFilter'
- $ref: '#/components/parameters/PaymentProviderTypeFilter'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentProvidersResponse'
example:
operation_id: v1_payments_providers_get
data:
- provider: barclays
display_name: Barclays
icon: https://www.thisisbud.com/provider/resource/#1
services:
- domestic-single-payment
- domestic-standing-order
- domestic-scheduled-payment
maintenance_status: active
maintenance_window:
start: 2019-08-07T11:48:00+0000
end: 2019-08-07T11:00:00+0000
country_code: GBR
implementation_type: OpenbankingUK
supported_currencies:
- GBP
required_actions:
- confirm_single_payment
- confirm_standing_order
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/payments/single/bud-pay-url:
post:
tags:
- Initiate Payment - Bud license
summary: Retrieve Bud Pay URL - Single Payment
description: Retrieve a Bud Pay URL to initiate a single payment. Please note that this endpoint should be used if you are using Bud as a Third Party Provider (TPP), i.e. you are not yourself regulated as an Payment Initiation Service Provider (PISP)
operationId: v1_payments_single_bud_pay_url_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentsSingleBudPayURLRequest'
examples:
Bud Pay URL UK:
value:
redirect_url: https://client-redirect-url/example
provider: natwest
provider_types:
- retail
payment_details:
reference: PAYMENT REFERENCE
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
sender:
user_id: client-defined-user-id
name: Mr TEST SENDER
amount:
value: '2.50'
currency: GBP
Bud Pay URL Europe:
value:
redirect_url: https://client-redirect-url/foo
provider: commerzbank
payment_details:
reference: REFERENCE FOR PAYMENT
recipient:
type: IBAN
name: MR TEST RECIPIENT
account_number: DE40100100103307118603
sender:
user_id: client-defined-user-id
name: Mr TEST SENDER
type: IBAN
account_number: DE50100100103307118608
amount:
value: '2.50'
currency: EUR
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/BudPayResponse'
example:
operation_id: v1_payments_single_bud_pay_url_post
data:
bud_pay_url: https://www.thisisbud.com/v1/payment/bud-pay
payment_id: 56caec01-85cc-4fc6-8080-cc0f7ed03a7e
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_single_bud_pay_url_post
code_id: failed_validation
message: Failed validation
errors:
redirect_url: This value should not be blank
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
callbacks:
payment-event:
'{$request.body#/endpoint}':
description: |
This callback is sent to your configured Payment Status Updates webhook URL once a payment task has been successfully completed.
post:
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Payment Update Notification Callback
security: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentStatusUpdatedNotificationBody'
example:
data:
payment_id: c8c934f0-366c-4656-a686-ada2aacd0d9f
service: domestic-single-payment
user_id: client-defined-user-id
event: payment.success
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/v1/payments/standing-order/bud-pay-url:
post:
tags:
- Initiate Payment - Bud license
summary: Retrieve Bud Pay URL - Standing Order
description: Retrieve a Bud Pay URL to initiate a Standing Order. Please note that this endpoint should be used if you are using Bud as a Third Party Provider (TPP), i.e. you are not yourself regulated as an Payment Initiation Service Provider (PISP)
operationId: v1_payments_standing_order_bud_pay_url_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentsStandingOrderBudPayURLRequest'
example:
redirect_url: https://client-redirect-url/example
provider_types:
- retail
provider: BankOfBudOBUK
standing_order_details:
reference: PAYMENT REFERENCE
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
sender:
user_id: client-defined-user-id
name: MR TEST SENDER
recurring_amount:
value: '2.50'
currency: GBP
first_payment_date: '2023-02-10T15:00:00Z'
last_payment_date: '2023-02-10T15:00:00Z'
frequency: monthly
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/BudPayResponse'
example:
operation_id: v1_payments_standing_order_bud_pay_url_post
data:
bud_pay_url: https://www.thisisbud.com/v1/payment/bud-pay
payment_id: 56caec01-85cc-4fc6-8080-cc0f7ed03a7e
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_standing_order_bud_pay_url_post
code_id: failed_validation
message: Failed validation
errors:
redirect_url: This value should not be blank
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
callbacks:
payment-event:
'{$request.body#/endpoint}':
description: |
This callback is sent to your configured Payment Status Updates webhook URL once a payment task has been successfully completed.
post:
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Payment Update Notification Callback
security: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentStatusUpdatedNotificationBody'
example:
data:
payment_id: c8c934f0-366c-4656-a686-ada2aacd0d9f
service: domestic-standing-order
user_id: client-defined-user-id
event: payment.success
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/v1/payments/scheduled/bud-pay-url:
post:
tags:
- Initiate Payment - Bud license
summary: Retrieve Bud Pay URL - Scheduled Payment
description: Retrieve a Bud Pay URL to initiate a Scheduled Payment. Please note that this endpoint should be used if you are using Bud as a Third Party Provider (TPP), i.e. you are not yourself regulated as an Payment Initiation Service Provider (PISP)
operationId: v1_payments_scheduled_bud_pay_url_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentsScheduledPaymentBudPayURLRequest'
example:
redirect_url: https://client-redirect-url/example
provider: natwest
provider_types:
- retail
scheduled_payment_details:
reference: PAYMENT REFERENCE
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
sender:
user_id: client-defined-user-id
name: MR TEST SENDER
amount:
value: '2.50'
currency: GBP
requested_execution_date: '2023-01-20T15:00:00Z'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/BudPayResponse'
example:
operation_id: v1_payments_scheduled_bud_pay_url_post
data:
bud_pay_url: https://www.thisisbud.com/v1/payment/bud-pay
payment_id: 56caec01-85cc-4fc6-8080-cc0f7ed03a7e
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_scheduled_bud_pay_url_post
code_id: failed_validation
message: Failed validation
errors:
redirect_url: This value should not be blank
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
callbacks:
payment-event:
'{$request.body#/endpoint}':
description: |
This callback is sent to your configured Payment Status Updates webhook URL once a payment task has been successfully completed.
post:
parameters:
- $ref: '#/components/parameters/SignatureHeaderParameter'
- $ref: '#/components/parameters/SigningIdHeaderParameter'
summary: Payment Update Notification Callback
security: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentStatusUpdatedNotificationBody'
example:
data:
payment_id: c8c934f0-366c-4656-a686-ada2aacd0d9f
service: domestic-scheduled-payment
user_id: client-defined-user-id
event: payment.success
responses:
'200':
description: Your server returns this code if it accepts the callback
'300':
description: The notification will not be retried, redirects will not be followed
'400':
description: The notification will not be retried
'500':
description: |
The request will be retried shortly. If it fails multiple times, we will stop attempting to deliver the notification for this single event.
/v1/payments/single:
post:
tags:
- Initiate Payment - Client license
summary: Create Single Payment
description: Create a unique single payment identifier and retrieve the authorisation url for the specific payment provider. Please note that this endpoint can only be used in the event that you are using Bud as a Technical Service Provider (TSP), i.e. you must be regulated as an Payment Initiation Service Provider (PISP)
operationId: v1_payments_single_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SinglePaymentRequest'
examples:
Create Payment UK:
value:
redirect_url: https://your-app.com/connected?my-parameter=xyz
provider: lloyds
payment_details:
reference: PAYMENT REFERENCE
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
sender:
user_id: client-defined-user-id
name: MR TEST SENDER
amount:
value: '2.50'
currency: GBP
Create Payment Europe:
value:
redirect_url: https://your-app.com/connected?my-parameter=xyz
provider: commerzbank
payment_details:
reference: PAYMENT REFERENCE
recipient:
type: IBAN
name: MR TEST RECIPIENT
account_number: DE40100100103307118605
sender:
user_id: client-defined-user-id
type: IBAN
name: MR TEST SENDER
account_number: DE02100100109307118608
amount:
value: '2.50'
currency: EUR
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/SinglePaymentResponse'
example:
operation_id: v1_payments_single_post
data:
payment_id: 56caec01-85cc-4fc6-8080-cc0f7ed03a7e
authorisation_url: https://www.thisisbud.com/provider/specific/redirect/url
required_action: confirm_single_payment
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_single_post
code_id: failed_validation
message: Failed validation
errors:
recipient.sort_code: Sort code must match `^\d{6}$`
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
get:
tags:
- Manage Payments
summary: Search for Single Payments
description: Retrieve and view the status of multiple payments
operationId: v1_payment_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/PaymentIdHeader'
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/PaymentSenderProviders'
- $ref: '#/components/parameters/PaymentStatusCodes'
- $ref: '#/components/parameters/PaymentDateFrom'
- $ref: '#/components/parameters/PaymentDateTo'
- $ref: '#/components/parameters/PaymentAmountFrom'
- $ref: '#/components/parameters/PaymentAmountTo'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/ListSinglePaymentResponse'
examples:
Payment Status List UK:
value:
operation_id: v1_payment_get
data:
- payment_id: 89f80199-1199-400e-9092-17208f6f39f5
organisation_id: 22f80199-1199-400e-9092-17208f6f39f0
client_id: 22f80199-1199-400e-9092-17208f6f39f0
method: FPS
reference: Rent
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
amount:
value: '10.00'
currency: GBP
sender:
user_id: client-defined-user-id
name: MR RANDOM SENDER
provider: Natwest
known_charges:
recipient_charge:
charge: '1.50'
currency: GBP
recipient_receives: '7.00'
sender_charge:
charge: '1.50'
currency: GBP
bank_sends: '10.00'
total_cost: '11.50'
state:
status_code: SETTLED
status_message: Payment Settlement Complete
history:
- datetime: '2020-02-02T12:29:33.428944815Z'
code: CREATED
message: Payment created
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AWAITING_AUTH
message: Awaiting Authentication
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AUTHENTICATED
message: Authenticated; Confirming Funds
- datetime: '2020-02-02T12:29:33.428944815Z'
code: FUNDS_CONFIRMED
message: Funds Confirmed; Awaiting Payment Initiation
- datetime: '2020-02-02T12:29:33.428944815Z'
code: INITIATING
message: Initiating Payment
- datetime: '2020-02-02T12:29:33.428944815Z'
code: ACCEPTED
message: Payment Order Accepted
- datetime: '2020-02-02T12:29:33.428944815Z'
code: SETTLED
message: Payment Settlement Complete
supplementary_status:
payment_order:
status: AcceptedSettlementInProgress
history:
- datetime: '2020-02-02T12:29:37.628944815Z'
status: Pending
- datetime: '2020-02-02T12:29:38.628944815Z'
status: AcceptedSettlementInProgress
consent:
status: Authorised
history:
- datetime: '2020-02-02T12:29:34.828944815Z'
status: AwaitingAuthorisation
- datetime: '2020-02-02T12:29:35.028944815Z'
status: Authorised
confirmation_of_funds:
status: Available
history:
- datetime: '2020-02-02T12:29:35.028944815Z'
status: Available
required_action: null
errors:
- code: FAILED_FUNDS_CONFIRMATION
description: The call to the provider to confirm funds returned an error
created_at: '2020-02-02T12:29:33.428944815Z'
metadata:
total_results: 1000000
results: 10
page: 1
total_pages: 100000
Payment Status List Europe:
value:
operation_id: v1_payment_get
data:
- payment_id: 89f80199-1199-400e-9092-17208f6f39f5
organisation_id: 22f80199-1199-400e-9092-17208f6f39f0
client_id: 22f80199-1199-400e-9092-17208f6f39f0
method: SEPA
reference: Rent
recipient:
type: IBAN
name: MR TEST RECIPIENT
account_number: DE40100100103307118605
amount:
value: '10.00'
currency: EUR
sender:
user_id: client-defined-user-id
type: IBAN
name: MR RANDOM SENDER
account_number: DE02100100109307118606
provider: commerzbank
known_charges:
recipient_charge:
charge: '1.50'
currency: EUR
recipient_receives: '7.00'
sender_charge:
charge: '1.50'
currency: EUR
bank_sends: '10.00'
total_cost: '11.50'
state:
status_code: SETTLED
status_message: Payment Settlement Complete
history:
- datetime: '2020-02-02T12:29:33.428944815Z'
code: CREATED
message: Payment created
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AWAITING_AUTH
message: Awaiting Authentication
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AUTHENTICATED
message: Authenticated; Confirming Funds
- datetime: '2020-02-02T12:29:33.428944815Z'
code: FUNDS_CONFIRMED
message: Funds Confirmed; Awaiting Payment Initiation
- datetime: '2020-02-02T12:29:33.428944815Z'
code: INITIATING
message: Initiating Payment
- datetime: '2020-02-02T12:29:33.428944815Z'
code: ACCEPTED
message: Payment Order Accepted
- datetime: '2020-02-02T12:29:33.428944815Z'
code: SETTLED
message: Payment Settlement Complete
supplementary_status:
payment_order:
status: AcceptedSettlementInProgress
history:
- datetime: '2020-02-02T12:29:37.628944815Z'
status: Pending
- datetime: '2020-02-02T12:29:38.628944815Z'
status: AcceptedSettlementInProgress
consent:
status: Authorised
history:
- datetime: '2020-02-02T12:29:34.828944815Z'
status: AwaitingAuthorisation
- datetime: '2020-02-02T12:29:35.028944815Z'
status: Authorised
confirmation_of_funds:
status: Available
history:
- datetime: '2020-02-02T12:29:35.028944815Z'
status: Available
required_action: null
errors:
- code: FAILED_FUNDS_CONFIRMATION
description: The call to the provider to confirm funds returned an error
created_at: '2020-02-02T12:29:33.428944815Z'
metadata:
total_results: 1000000
results: 10
page: 1
total_pages: 100000
'401':
description: Unauthorised request
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_payment_id_get
code_id: failed_validation
message: Failed validation
errors:
payment_id: Value not found
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/payments/authorisation-codes:
post:
tags:
- Initiate Payment - Client license
summary: Submit Authorisation Codes
description: |
When using Bud as a TSP (Technical Service Provider) and doing full app-to-app authorisation, the customer is returned from the provider directly back to your app. Your app will then need to send all the query and hash fragment parameters to Bud so that we can continue with the payment flow.
Query and fragment parameters should be merged with query taking precedence. If you receive a request /path?a=1#a=2&b=3 then you should perform this request with {"a":"1","b":"3"}. Given the nature of the fragment queries most server side languages will not process these so javascript may be required to correctly gather both parameters.
Regardless of what parameters are present, all of them should be sent to Bud so that we can choose to either continue the connection or to map and record the error.
State, Code and error are the most common parameters you will see, but this object may contain any number of unspecified properties. Currently state is a common property among all authorisation flows and is the current task ID. The state property is not guaranteed for the future of this API contract and will not be treated as backwards incompatible if a new authentication flow does not use it.
operationId: v1_payments_authorisation_codes_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorisationCodesRequest'
examples:
Success:
value:
state: e017bd1c-9b39-40cc-b9ec-e21fce26719e
code: 803A940E-2416-4A34-BF5F-4AC8C9977AC4
Error:
value:
state: e017bd1c-9b39-40cc-b9ec-e21fce26719e
error: access_denied
responses:
'200':
description: Successful request.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentsAuthorisationCodesResponse'
example:
operation_id: v1_payments_authorisation_codes_post
data:
result: success
payment_id: 5edb14fe-ab4b-4357-ae15-98765c599fb5
payment_type: single
'400':
description: Request contained invalid/missing data
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentsErrorResponse'
example:
operation_id: v1_payments_authorisation_codes_post
code_id: failed_validation
message: Failed validation
errors:
payment:
- unable to find payment for [Payment ID]
'500':
description: An internal server error has occurred
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentsErrorResponse'
example:
operation_id: v1_payments_authorisation_codes_post
code_id: internal_error
message: Internal server error has occurred
errors:
db: could not fetch payment resource
/v1/payments/single/{payment_id}/confirm:
post:
tags:
- Initiate Payment - Client license
summary: Confirm Single Payment
description: Confirm and execute payment order for a specific payment.
operationId: v1_payments_single_confirm_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/ClientId'
responses:
'201':
description: Payment order created successfully
content:
application/json:
example:
operation_id: v1_payments_single_confirm_post
'400':
description: Not allowed to confirm payment. Either there is no consent, not authorised or the payment order has already been created
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_single_confirm_post
code_id: failed_validation
message: Failed validation
errors:
payment:
- Payment initiation failed
'401':
description: Unauthorised request
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_single_confirm_post
code_id: failed_validation
message: Failed validation
errors:
payment_id: Value not found
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/payments/single/{payment_id}:
get:
tags:
- Manage Payments
summary: Retrieve Single Payment Status
description: Retrieve and view the status of a payment
operationId: v1_payments_single_payment_id_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/ClientId'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/StatusSinglePaymentResponse'
examples:
Payment Status UK:
value:
operation_id: v1_payments_single_payment_id_get
data:
payment_id: 89f80199-1199-400e-9092-17208f6f39f5
organisation_id: 22f80199-1199-400e-9092-17208f6f39f0
client_id: 22f80199-1199-400e-9092-17208f6f39f0
method: FPS
reference: Rent
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
amount:
value: '10.00'
currency: GBP
sender:
user_id: client-defined-user-id
name: MR TEST SENDER
provider: Natwest
known_charges:
recipient_charge:
charge: '1.50'
currency: GBP
recipient_receives: '7.00'
sender_charge:
charge: '1.50'
currency: GBP
bank_sends: '10.00'
total_cost: '11.50'
state:
status_code: SETTLED
status_message: Payment Settlement Complete
history:
- datetime: '2020-02-02T12:29:33.428944815Z'
code: CREATED
message: Payment created
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AWAITING_AUTH
message: Awaiting Authentication
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AUTHENTICATED
message: Authenticated; Confirming Funds
- datetime: '2020-02-02T12:29:33.428944815Z'
code: FUNDS_CONFIRMED
message: Funds Confirmed; Awaiting Payment Initiation
- datetime: '2020-02-02T12:29:33.428944815Z'
code: INITIATING
message: Initiating Payment
- datetime: '2020-02-02T12:29:33.428944815Z'
code: ACCEPTED
message: Payment Order Accepted
- datetime: '2020-02-02T12:29:33.428944815Z'
code: SETTLED
message: Payment Settlement Complete
supplementary_status:
payment_order:
status: AcceptedSettlementInProgress
history:
- datetime: '2020-02-02T12:29:37.628944815Z'
status: Pending
- datetime: '2020-02-02T12:29:38.628944815Z'
status: AcceptedSettlementInProgress
consent:
status: Authorised
history:
- datetime: '2020-02-02T12:29:34.828944815Z'
status: AwaitingAuthorisation
- datetime: '2020-02-02T12:29:35.028944815Z'
status: Authorised
confirmation_of_funds:
status: Available
history:
- datetime: '2020-02-02T12:29:35.028944815Z'
status: Available
required_action: null
errors:
- code: FAILED_FUNDS_CONFIRMATION
description: The call to the provider to confirm funds returned an error
created_at: '2020-02-02T12:29:33.428944815Z'
metadata: {}
Payment Status Europe:
value:
operation_id: v1_payments_single_payment_id_get
data:
payment_id: 89f80199-1199-400e-9092-17208f6f39f5
organisation_id: 22f80199-1199-400e-9092-17208f6f39f0
client_id: 22f80199-1199-400e-9092-17208f6f39f0
method: SEPA
reference: Rent
recipient:
type: IBAN
name: MR TEST RECIPIENT
account_number: DE40100100103307118609
amount:
value: '10.00'
currency: EUR
sender:
user_id: client-defined-user-id
type: IBAN
name: MR TEST SENDER
account_number: DE02100100109307118606
provider: commerzbank
known_charges:
recipient_charge:
charge: '1.50'
currency: EUR
recipient_receives: '7.00'
sender_charge:
charge: '1.50'
currency: EUR
bank_sends: '10.00'
total_cost: '11.50'
state:
status_code: SETTLED
status_message: Payment Settlement Complete
history:
- datetime: '2020-02-02T12:29:33.428944815Z'
code: CREATED
message: Payment created
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AWAITING_AUTH
message: Awaiting Authentication
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AUTHENTICATED
message: Authenticated; Confirming Funds
- datetime: '2020-02-02T12:29:33.428944815Z'
code: FUNDS_CONFIRMED
message: Funds Confirmed; Awaiting Payment Initiation
- datetime: '2020-02-02T12:29:33.428944815Z'
code: INITIATING
message: Initiating Payment
- datetime: '2020-02-02T12:29:33.428944815Z'
code: ACCEPTED
message: Payment Order Accepted
- datetime: '2020-02-02T12:29:33.428944815Z'
code: SETTLED
message: Payment Settlement Complete
supplementary_status:
payment_order:
status: AcceptedSettlementInProgress
history:
- datetime: '2020-02-02T12:29:37.628944815Z'
status: Pending
- datetime: '2020-02-02T12:29:38.628944815Z'
status: AcceptedSettlementInProgress
consent:
status: Authorised
history:
- datetime: '2020-02-02T12:29:34.828944815Z'
status: AwaitingAuthorisation
- datetime: '2020-02-02T12:29:35.028944815Z'
status: Authorised
confirmation_of_funds:
status: Available
history:
- datetime: '2020-02-02T12:29:35.028944815Z'
status: Available
required_action: null
errors:
- code: FAILED_FUNDS_CONFIRMATION
description: The call to the provider to confirm funds returned an error
created_at: '2020-02-02T12:29:33.428944815Z'
metadata: {}
'401':
description: Unauthorised request
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_single_payment_id_get
code_id: failed_validation
message: Failed validation
errors:
payment_id: Value not found
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/payments/standing-order:
post:
tags:
- Initiate Payment - Client license
summary: Create Standing Order
description: Create a new Standing Order payment identifier and retrieve the authorisation url for the specific payment provider. Please note that this endpoint can only be used in the event that you are using Bud as a Technical Service Provider (TSP), i.e. you must be regulated as an Payment Initiation Service Provider (PISP)
operationId: v1_payments_standing_order_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateStandingOrderRequest'
example:
redirect_url: https://your-app.com/connected?my-parameter=xyz
provider: lloyds
standing_order_details:
reference: PAYMENT REFERENCE
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
sender:
user_id: client-defined-user-id
name: MR TEST SENDER
recurring_amount:
value: '2.50'
currency: GBP
first_payment_date: '2020-02-02T12:29:33.428944815Z'
last_payment_date: '2021-02-02T12:29:33.428944815Z'
frequency: monthly
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateStandingOrderResponse'
example:
operation_id: v1_payments_standing_order_post
data:
authorisation_url: https://www.thisisbud.com/provider/specific/redirect/url
payment_id: 56caec01-85cc-4fc6-8080-cc0f7ed03a7e
required_action: confirm_standing_order
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_standing_order_post
code_id: failed_validation
message: Failed validation
errors:
recipient.sort_code: Sort code must match `^\d{6}$`
standing_order_details.recipient.name: Name must not be empty
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
get:
tags:
- Manage Payments
summary: Search for Standing Orders
description: Retrieve and view the status of multiple Standing Orders
operationId: v1_payments_standing_order_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/PaymentIdHeader'
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/PaymentSenderProviders'
- $ref: '#/components/parameters/PaymentStatusCodes'
- $ref: '#/components/parameters/PaymentDateFrom'
- $ref: '#/components/parameters/PaymentDateTo'
- $ref: '#/components/parameters/PaymentAmountFrom'
- $ref: '#/components/parameters/PaymentAmountTo'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/ListStandingOrderResponse'
example:
operation_id: v1_payments_standing_order_get
data:
- payment_id: 89f80199-1199-400e-9092-17208f6f39f5
organisation_id: 22f80199-1199-400e-9092-17208f6f39f0
client_id: 22f80199-1199-400e-9092-17208f6f39f0
reference: Rent
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
recurring_amount:
value: '10.00'
currency: GBP
sender:
user_id: client-defined-user-id
name: MR RANDOM SENDER
provider: Natwest
known_charges:
recipient_charge:
charge: '1.50'
currency: GBP
recipient_receives: '7.00'
sender_charge:
charge: '1.50'
currency: GBP
bank_sends: '10.00'
total_cost: '11.50'
state:
status_code: COMPLETED
status_message: Standing Order Creation Completed
history:
- datetime: '2020-02-02T12:29:33.428944815Z'
code: CREATED
message: Standing Order Created
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AWAITING_AUTH
message: Awaiting Customer Authentication
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AUTH_COMPLETED
message: Authentication Completed
- datetime: '2020-02-02T12:29:33.428944815Z'
code: PENDING
message: Payment Order Pending
- datetime: '2020-02-02T12:29:33.428944815Z'
code: COMPLETED
message: Standing Order Creation Completed
errors:
- code: FAILED
description: The call to the provider to confirm funds returned an error
created_at: '2020-02-02T12:29:33.428944815Z'
first_payment_date: '2020-02-02T12:29:33.428944815Z'
last_payment_date: '2021-02-02T12:29:33.428944815Z'
frequency: monthly
required_action: null
metadata:
total_results: 1000000
results: 10
page: 1
total_pages: 100000
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_standing_order_get
code_id: failed_validation
message: Failed validation
errors:
filter: X-Date-From is in the wrong format (expected 2006-01-02T15:04:05Z)
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/payments/standing-order/{payment_id}/confirm:
post:
tags:
- Initiate Payment - Client license
summary: Confirm Standing Order
description: Confirm and execute a Standing Order for a specific payment id.
operationId: v1_payments_standing_order_confirm_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/ClientId'
responses:
'201':
description: Standing order created successfully
content:
application/json:
example:
operation_id: v1_payments_standing_order_confirm_post
'400':
description: Not allowed to confirm payment. Either there is no consent, not authorised or the payment order has already been created
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_standing_order_confirm_post
code_id: failed_validation
message: Failed validation
errors:
payment: Payment initiation failed
'401':
description: Unauthorised request
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_standing_order_confirm_post
code_id: failed_validation
message: Failed validation
errors:
payment_id: Value not found
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/payments/standing-order/{payment_id}:
get:
tags:
- Manage Payments
summary: Retrieve Standing Order Payment Status
description: Retrieve and view the status of a specific Standing Order payment
operationId: v1_payments_standing_order_payment_id_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/ClientId'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/StatusStandingOrderResponse'
example:
operation_id: v1_payments_standing_order_payment_id_get
data:
payment_id: 89f80199-1199-400e-9092-17208f6f39f5
organisation_id: 22f80199-1199-400e-9092-17208f6f39f0
client_id: 22f80199-1199-400e-9092-17208f6f39f0
method: FPS
reference: Rent
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
recurring_amount:
value: '10.00'
currency: GBP
sender:
user_id: client-defined-user-id
name: MR TEST SENDER
provider: Natwest
known_charges:
recipient_charge:
charge: '1.50'
currency: GBP
recipient_receives: '7.00'
sender_charge:
charge: '1.50'
currency: GBP
bank_sends: '10.00'
total_cost: '11.50'
state:
status_code: COMPLETED
status_message: Standing Order Creation Completed
history:
- datetime: '2020-02-02T12:29:33.428944815Z'
code: CREATED
message: Standing Order Created
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AWAITING_AUTH
message: Awaiting Customer Authentication
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AUTH_COMPLETED
message: Authentication Completed
- datetime: '2020-02-02T12:29:33.428944815Z'
code: PENDING
message: Payment Order Pending
- datetime: '2020-02-02T12:29:33.428944815Z'
code: COMPLETED
message: Standing Order Creation Completed
errors:
- code: FAILED
description: The call to the provider to confirm funds returned an error
created_at: '2020-02-02T12:29:33.428944815Z'
first_payment_date: '2020-02-02T12:29:33.428944815Z'
last_payment_date: '2021-02-02T12:29:33.428944815Z'
frequency: monthly
required_action: null
metadata: {}
'401':
description: Unauthorised request
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_standing_order_get
code_id: failed_validation
message: Failed validation
errors:
payment_id: Value not found
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/payments/scheduled:
post:
tags:
- Initiate Payment - Client license
summary: Create Scheduled Payment
description: Create a new scheduled payment identifier and retrieve the authorisation url for the specific payment provider. Please note that this endpoint can only be used in the event that you are using Bud as a Technical Service Provider (TSP), i.e. you must be regulated as an Payment Initiation Service Provider (PISP)
operationId: v1_payments_scheduled_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScheduledPaymentRequest'
example:
redirect_url: https://your-app.com/connected?my-parameter=xyz
provider: lloyds
scheduled_payment_details:
reference: PAYMENT REFERENCE
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
sender:
user_id: client-defined-user-id
name: MR TEST SENDER
amount:
value: '2.50'
currency: GBP
requested_execution_date: '2020-02-02T12:29:33.428944815Z'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScheduledPaymentResponse'
example:
operation_id: v1_payments_scheduled_post
data:
authorisation_url: https://www.thisisbud.com/provider/specific/redirect/url
payment_id: 56caec01-85cc-4fc6-8080-cc0f7ed03a7e
required_action: confirm_scheduled_payment
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_scheduled_post
code_id: failed_validation
message: Failed validation
errors:
recipient.sort_code: Sort code must match `^\d{6}$`
standing_order_details.recipient.name: Name must not be empty
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
get:
tags:
- Manage Payments
summary: Search for Scheduled Payments
description: Retrieve and view the status of multiple Scheduled Payments
operationId: v1_payments_scheduled_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/PaymentIdHeader'
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/PaymentSenderProviders'
- $ref: '#/components/parameters/PaymentStatusCodes'
- $ref: '#/components/parameters/PaymentDateFrom'
- $ref: '#/components/parameters/PaymentDateTo'
- $ref: '#/components/parameters/PaymentAmountFrom'
- $ref: '#/components/parameters/PaymentAmountTo'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/ListScheduledPaymentResponse'
example:
operation_id: v1_payments_scheduled_get
data:
- payment_id: 89f80199-1199-400e-9092-17208f6f39f5
organisation_id: 22f80199-1199-400e-9092-17208f6f39f0
client_id: 22f80199-1199-400e-9092-17208f6f39f0
reference: Rent
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
amount:
value: '10.00'
currency: GBP
sender:
user_id: client-defined-user-id
name: MR RANDOM SENDER
provider: Natwest
known_charges:
recipient_charge:
charge: '1.50'
currency: GBP
recipient_receives: '7.00'
sender_charge:
charge: '1.50'
currency: GBP
bank_sends: '10.00'
total_cost: '11.50'
state:
status_code: COMPLETED
status_message: Scheduled Payment Creation Completed
history:
- datetime: '2020-02-02T12:29:33.428944815Z'
code: CREATED
message: Scheduled Payment Created
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AWAITING_AUTH
message: Awaiting Customer Authentication
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AUTH_COMPLETED
message: Authentication Completed
- datetime: '2020-02-02T12:29:33.428944815Z'
code: PENDING
message: Payment Order Pending
- datetime: '2020-02-02T12:29:33.428944815Z'
code: COMPLETED
message: Scheduled Payment Creation Completed
errors:
- code: FAILED
description: The call to the provider to confirm funds returned an error
created_at: '2020-02-02T12:29:33.428944815Z'
requested_execution_date: '2020-02-02T12:29:33.428944815Z'
metadata:
total_results: 1000000
results: 10
page: 1
total_pages: 100000
'400':
description: The request contains an invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_scheduled_get
code_id: failed_validation
message: Failed validation
errors:
filter: X-Date-From is in the wrong format (expected 2006-01-02T15:04:05Z)
'401':
description: Unauthorised request
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/payments/scheduled/{payment_id}/confirm:
post:
tags:
- Initiate Payment - Client license
summary: Confirm Scheduled Payment
description: Confirm and execute a Scheduled Payment for a specific payment id.
operationId: v1_payments_scheduled_payment_id_confirm_post
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/ClientId'
responses:
'201':
description: Request to create scheduled payment succeeded
content:
application/json:
example:
operation_id: v1_payments_scheduled_payment_id_confirm_post
'400':
description: Not allowed to confirm payment. Either there is no consent, not authorised or the payment order has already been created
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_scheduled_payment_id_confirm_post
code_id: failed_validation
message: Failed validation
errors:
payment: Payment initiation failed
'401':
description: Unauthorised request
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_scheduled_payment_id_confirm_post
code_id: failed_validation
message: Failed validation
errors:
payment_id: Value not found
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/v1/payments/scheduled/{payment_id}:
get:
tags:
- Manage Payments
summary: Retrieve Scheduled Payment Status
description: Retrieve and view the status of a specific Scheduled payment
operationId: v1_payments_scheduled_payment_id_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/ClientId'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/GetScheduledPaymentResponse'
example:
operation_id: v1_payments_scheduled_payment_id_get
data:
payment_id: 89f80199-1199-400e-9092-17208f6f39f5
organisation_id: 22f80199-1199-400e-9092-17208f6f39f0
client_id: 22f80199-1199-400e-9092-17208f6f39f0
method: FPS
reference: Rent
recipient:
type: SortCodeAccountNumber
name: MR TEST RECIPIENT
account_number: '01234501234567'
amount:
value: '10.00'
currency: GBP
sender:
user_id: client-defined-user-id
name: MR TEST SENDER
provider: Natwest
known_charges:
recipient_charge:
charge: '1.50'
currency: GBP
recipient_receives: '7.00'
sender_charge:
charge: '1.50'
currency: GBP
bank_sends: '10.00'
total_cost: '11.50'
state:
status_code: COMPLETED
status_message: Scheduled Payment Creation Completed
history:
- datetime: '2020-02-02T12:29:33.428944815Z'
code: CREATED
message: Scheduled Payment Created
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AWAITING_AUTH
message: Awaiting Customer Authentication
- datetime: '2020-02-02T12:29:33.428944815Z'
code: AUTH_COMPLETED
message: Authentication Completed
- datetime: '2020-02-02T12:29:33.428944815Z'
code: PENDING
message: Payment Order Pending
- datetime: '2020-02-02T12:29:33.428944815Z'
code: COMPLETED
message: Scheduled Payment Creation Completed
errors:
- code: FAILED
description: The call to the provider to confirm funds returned an error
created_at: '2020-02-02T12:29:33.428944815Z'
requested_execution_date: '2020-02-02T12:29:33.428944815Z'
required_action: null
'401':
description: Unauthorised request
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
example:
operation_id: v1_payments_scheduled_payment_id_get
code_id: failed_validation
message: Failed validation
errors:
payment_id: Value not found
'405':
description: An unexpected HTTP method was used
5XX:
description: An unexpected error occurred on the server side
/characteristics/v1/customer:
get:
tags:
- Retrieve Customer Characteristics
summary: Retrieve Customer Characteristics
description: |
Retrieves a collection of characteristics associated with an individual Customer.
For data on why an individual characteristic applies to a Customer, use the relevant detailed endpoint.
The currently supported characteristics are:
| Characteristic | Description |
|:---------------|:-----------------------------------------------------------|
| `credit_card` | Customer has made credit card repayments |
| `loan` | Customer has made loan repayments (excluding credit cards) |
| `overdraft` | Customer has paid overdraft fees |
| `saver` | Customer has savings transactions |
New characteristics will be released and added to this list without a breaking change notice.
operationId: characteristics_v1_customer_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomerCharacteristicsResponse'
examples:
Multiple Characteristics:
value:
operation_id: characteristics_v1_customer_get
data:
- type: credit_card
link: characteristics/v1/customer/credit_card
- type: loan
link: characteristics/v1/customer/loan
- type: overdraft
link: characteristics/v1/customer/overdraft
- type: saver
link: characteristics/v1/customer/saver
No Characteristics:
value:
operation_id: characteristics_v1_customer_get
data: []
'401':
description: Unauthorised request
5XX:
description: An unexpected error occurred on the server side
/characteristics/v1/customer/credit-card:
get:
tags:
- Retrieve Customer Characteristics
summary: Retrieve Customer Characteristics - Credit Card
description: |
Retrieves detailed information for a customer that marks them as a credit card user.
operationId: characteristics_v1_customer_credit_card_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetCreditCardCharacteristicsResponse'
example:
operation_id: characteristics_v1_customer_credit_card_get
data:
credit_card_transactions:
- transaction_id: 864a3efc-6104-4dde-99a0-c3d91a8bcecf
account_id: ad7d5904-39ab-4736-b726-5792c7a2146e
credit_debit_indicator: debit
description: CREDIT CARD PAYMENT
provider: BankOfBud
status: booked
amount:
value: '1234.56'
currency: GBP
date_time: '2023-07-03T10:00:00Z'
enrichments:
categories:
l1:
slug: borrowing_and_loans
confidence: '0.99'
l2:
slug: credit_cards
confidence: '0.99'
credit_card_transaction_totals:
- amount:
value: '1234.56'
currency: GBP
credit_debit_indicator: debit
'401':
description: Unauthorised request
5XX:
description: An unexpected error occurred on the server side
/characteristics/v1/customer/loan:
get:
tags:
- Retrieve Customer Characteristics
summary: Retrieve Customer Characteristics - Loan
description: |
Retrieves detailed information for a customer that marks them as a loan user.
operationId: characteristics_v1_customer_loan_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetLoanCharacteristicsResponse'
example:
operation_id: characteristics_v1_customer_loan_get
data:
loan_transactions:
- transaction_id: 864a3efc-6104-4dde-99a0-c3d91a8bcecf
account_id: ad7d5904-39ab-4736-b726-5792c7a2146e
credit_debit_indicator: debit
description: CAR LOAN REPAYMENT
provider: BankOfBud
status: booked
amount:
value: '1234.56'
currency: GBP
date_time: '2023-07-03T10:00:00Z'
enrichments:
categories:
l1:
slug: borrowing_and_loans
confidence: '0.92'
l2:
slug: vehicle_loan
confidence: '0.80'
loan_transaction_totals:
- amount:
value: '1234.56'
currency: GBP
credit_debit_indicator: debit
'401':
description: Unauthorised request
5XX:
description: An unexpected error occurred on the server side
/characteristics/v1/customer/overdraft:
get:
tags:
- Retrieve Customer Characteristics
summary: Retrieve Customer Characteristics - Overdraft
description: |
Retrieves detailed information for a customer that marks them as an overdraft user.
operationId: characteristics_v1_customer_overdraft_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetOverdraftCharacteristicsResponse'
example:
operation_id: characteristics_v1_customer_overdraft_get
data:
overdraft_transactions:
- transaction_id: 864a3efc-6104-4dde-99a0-c3d91a8bcecf
account_id: ad7d5904-39ab-4736-b726-5792c7a2146e
credit_debit_indicator: debit
description: OVERDRAFT FEE
provider: BankOfBud
status: booked
amount:
value: '12.34'
currency: GBP
date_time: '2023-07-03T10:00:00Z'
enrichments:
categories:
l1:
slug: banking
confidence: '0.92'
l2:
slug: overdraft_fees
confidence: '0.80'
overdraft_transaction_totals:
- amount:
value: '12.34'
currency: GBP
credit_debit_indicator: debit
'401':
description: Unauthorised request
5XX:
description: An unexpected error occurred on the server side
/characteristics/v1/customer/saver:
get:
tags:
- Retrieve Customer Characteristics
summary: Retrieve Customer Characteristics - Saver
description: |
Retrieves detailed information for a customer that marks them as a saver.
operationId: characteristics_v1_customer_saver_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetSaverCharacteristicsResponse'
example:
operation_id: characteristics_v1_customer_saver_get
data:
saver_transactions:
- transaction_id: 864a3efc-6104-4dde-99a0-c3d91a8bcecf
account_id: ad7d5904-39ab-4736-b726-5792c7a2146e
credit_debit_indicator: debit
description: SAVINGS
provider: BankOfBud
status: booked
amount:
value: '150.00'
currency: GBP
date_time: '2023-07-03T10:00:00Z'
enrichments:
categories:
l1:
slug: pensions_savings_and_investments
confidence: '0.99'
l2:
slug: savings
confidence: '0.99'
saver_transactions_totals:
- amount:
value: '12.34'
currency: GBP
credit_debit_indicator: debit
'401':
description: Unauthorised request
5XX:
description: An unexpected error occurred on the server side
/insights/v1/actionable/balances:
get:
tags:
- Retrieve Actionable Insights
summary: Retrieve Balances Actionable Insights
description: |
Generate balances actionable insights.
> 📘 Note:
>
> For more information about Actionable Insights, please refer to our [guide](https://docs.thisisbud.com/docs/actionable-insights).
operationId: insights_v1_actionable_balances_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/BalancesEnabledInsights'
- $ref: '#/components/parameters/CloseToCreditLimitPercentageUtilisationThreshold'
- $ref: '#/components/parameters/LowBalanceBalanceThreshold'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BalancesInsightsResponse'
example:
operation_id: insights_v1_actionable_balances_get
data:
insights:
- id: in_overdraft_8789764a-df2f-4589-b550-00bcd0e9cb2c
type: in_overdraft
account_id: 8789764a-df2f-4589-b550-00bcd0e9cb2c
balance:
value: '100.00'
currency: GBP
credit_debit_indicator: debit
threshold:
value: '0.00'
currency: GBP
credit_debit_indicator: debit
_links:
details: https://domain/insights/v1/actionable/balances/in_overdraft/in_overdraft_8789764a-df2f-4589-b550-00bcd0e9cb2c/details
metadata:
results: 1
from: '2022-11-01T00:00:00Z'
to: '2023-05-16T17:30:00Z'
options: []
/insights/v1/actionable/balances/{type}/{id}/details:
get:
tags:
- Retrieve Actionable Insights
summary: Retrieve Balances Actionable Insight Details
description: |
Retrieve insight-specific details and transaction and account data responsible for the triggered balances insight of the given type and ID.
> 📘 Note:
>
> For more information about Actionable Insights, please refer to our [guide](https://docs.thisisbud.com/docs/actionable-insights).
operationId: insights_v1_actionable_balances_details_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/BalancesInsightType'
- $ref: '#/components/parameters/InsightID'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BalancesInsightsDataResponse'
example:
operation_id: insights_v1_actionable_balances_details_get
data:
id: in_overdraft_ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
type: in_overdraft
caused_by:
accounts:
- account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
currency: GBP
holder:
name: David Smith
relationship: unknown
account_name: My Current Account
account_type: current_account
usage_type: personal
provider: BankOfBud
identifiers:
uk_sort_code: '126432'
uk_account_number: '31510604'
balances:
- date: '2023-05-12T00:00:00Z'
amount:
value: '100.00'
currency: GBP
type: interim_booked
credit_debit_indicator: debit
- date: '2023-05-12T00:00:00Z'
amount:
value: '100.00'
currency: GBP
type: expected
credit_debit_indicator: debit
credit_lines:
- date: '2023-05-12T00:00:00Z'
type: credit
amount:
value: '1000.00'
currency: GBP
transactions: []
details: {}
metadata:
from: '2022-11-01T00:00:00Z'
to: '2023-05-16T17:30:00Z'
options: []
'404':
description: Insight not found. This can occur if the returned insight was invalidated by an account refresh or other change to customer data.
/insights/v1/actionable/income:
get:
tags:
- Retrieve Actionable Insights
summary: Retrieve Income Actionable Insights
description: |
Generate income actionable insights.
> 📘 Note:
>
> For more information about Actionable Insights, please refer to our [guide](https://docs.thisisbud.com/docs/actionable-insights).
operationId: insights_v1_actionable_income_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/IncomeEnabledInsights'
- $ref: '#/components/parameters/GamblingIncomeMinimumMonthlyThreshold'
- $ref: '#/components/parameters/GamblingIncomeMinimumPercentageTotalThreshold'
- $ref: '#/components/parameters/LateIncomeMinimumValueThreshold'
- $ref: '#/components/parameters/LateIncomeMinimumDaysLateThreshold'
- $ref: '#/components/parameters/PensionIncomeMinimumMonthlyThreshold'
- $ref: '#/components/parameters/PensionIncomeMinimumPercentageTotalThreshold'
- $ref: '#/components/parameters/RegularIncomeChangedMinimumAbsoluteChangeThreshold'
- $ref: '#/components/parameters/RegularIncomeChangedMinimumPercentageChangeThreshold'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IncomeInsightsResponse'
example:
operation_id: insights_v1_actionable_income_get
data:
insights:
- id: late_income_8789764a-df2f-4589-b550-00bcd0e9cb2c
type: late_income
transactions:
- transaction_id: a_transaction_id
account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
provider: a_bank_account_provider
description: SALARY
credit_debit_indicator: credit
status: booked
suggested_description: salary
amount:
value: '3000.00'
currency: GBP
date_time: '2023-04-10T10:00:00Z'
enrichments:
categories:
l1:
slug: income
confidence: '0.99'
l2:
slug: employment_income
confidence: '0.98'
regularity:
frequency: monthly
predicted_date_times:
- '2023-05-10T10:00:00Z'
_links:
details: https://domain/insights/v1/actionable/income/late_income/late_income_8789764a-df2f-4589-b550-00bcd0e9cb2c/details
totals:
income:
- value: '12000.00'
currency: GBP
expenditure:
- value: '14000.00'
currency: GBP
metadata:
results: 1
from: '2022-11-01T00:00:00Z'
to: '2023-05-16T17:30:00Z'
options:
- insight_type: late_income
option: minimum_days_late_threshold
value: '3'
- insight_type: late_income
option: minimum_value_threshold
value: '100.00'
/insights/v1/actionable/income/{type}/{id}/details:
get:
tags:
- Retrieve Actionable Insights
summary: Retrieve Income Actionable Insight Details
description: |
Retrieve insight-specific details and transaction and account data responsible for the triggered income insight of the given type and ID.
> 📘 Note:
>
> For more information about Actionable Insights, please refer to our [guide](https://docs.thisisbud.com/docs/actionable-insights).
operationId: insights_v1_actionable_income_details_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/IncomeInsightType'
- $ref: '#/components/parameters/InsightID'
- $ref: '#/components/parameters/GamblingIncomeMinimumMonthlyThreshold'
- $ref: '#/components/parameters/GamblingIncomeMinimumPercentageTotalThreshold'
- $ref: '#/components/parameters/LateIncomeMinimumValueThreshold'
- $ref: '#/components/parameters/LateIncomeMinimumDaysLateThreshold'
- $ref: '#/components/parameters/PensionIncomeMinimumMonthlyThreshold'
- $ref: '#/components/parameters/PensionIncomeMinimumPercentageTotalThreshold'
- $ref: '#/components/parameters/RegularIncomeChangedMinimumAbsoluteChangeThreshold'
- $ref: '#/components/parameters/RegularIncomeChangedMinimumPercentageChangeThreshold'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IncomeInsightsDataResponse'
example:
operation_id: insights_v1_actionable_income_details_get
data:
id: late_income_8789764a-df2f-4589-b550-00bcd0e9cb2c
type: late_income
caused_by:
accounts:
- account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
currency: GBP
holder:
name: David Smith
relationship: unknown
account_name: My Current Account
account_type: current_account
usage_type: personal
provider: BankOfBud
identifiers:
uk_sort_code: '126432'
uk_account_number: '31510604'
balances:
- date: '2023-05-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
- date: '2023-05-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: expected
credit_debit_indicator: credit
credit_lines:
- date: '2023-05-12T00:00:00Z'
type: credit
amount:
value: '1000.00'
currency: GBP
transactions:
- transaction_id: a_transaction_id
account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
provider: a_bank_account_provider
description: SALARY
credit_debit_indicator: credit
status: booked
suggested_description: salary
amount:
value: '2400.00'
currency: GBP
date_time: '2023-05-05T10:00:00Z'
enrichments:
categories:
l1:
slug: income
confidence: '0.99'
l2:
slug: employment_income
confidence: '0.98'
regularity:
frequency: monthly
confidence:
predicted_date_times:
- '2023-05-10T10:00:00Z'
details:
days_late: 6
expected_date_time: '2023-05-10T10:00:00Z'
metadata:
from: '2022-11-01T00:00:00Z'
to: '2023-05-16T17:30:00Z'
options:
- insight_type: late_income
option: minimum_days_late_threshold
value: '3'
- insight_type: late_income
option: minimum_value_threshold
value: '100.00'
'404':
description: Insight not found. This can occur if the returned insight was invalidated by an account refresh or other change to customer data.
/insights/v1/actionable/spending:
get:
tags:
- Retrieve Actionable Insights
summary: Retrieve Spending Actionable Insights
description: |
Generate spending actionable insights.
> 📘 Note:
>
> For more information about Actionable Insights, please refer to our [guide](https://docs.thisisbud.com/docs/actionable-insights).
operationId: insights_v1_actionable_spending_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/SpendingEnabledInsights'
- $ref: '#/components/parameters/LatePaymentMinimumValueThreshold'
- $ref: '#/components/parameters/LatePaymentMinimumDaysLateThreshold'
- $ref: '#/components/parameters/RegularPaymentChangedMinimumAbsoluteChangeThreshold'
- $ref: '#/components/parameters/RegularPaymentChangedMinimumPercentageChangeThreshold'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SpendingInsightsResponse'
example:
operation_id: insights_v1_actionable_spending_get
data:
insights:
- id: late_payment_8789764a-df2f-4589-b550-00bcd0e9cb2c
type: late_payment
transactions:
- transaction_id: a_transaction_id
account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
provider: a_bank_account_provider
description: MORTGAGE
credit_debit_indicator: debit
status: booked
suggested_description: mortgage
amount:
value: '1400.00'
currency: GBP
date_time: '2023-04-10T10:00:00Z'
enrichments:
categories:
l1:
slug: mortgage_and_rent
confidence: '0.99'
l2:
slug: mortgage
confidence: '0.98'
regularity:
frequency: monthly
predicted_date_times:
- '2023-05-10T10:00:00Z'
_links:
details: https://domain/insights/v1/actionable/spending/late_income/late_income_8789764a-df2f-4589-b550-00bcd0e9cb2c/details
totals:
income:
- value: '12000.00'
currency: GBP
expenditure:
- value: '14000.00'
currency: GBP
metadata:
results: 1
from: '2022-11-01T00:00:00Z'
to: '2023-05-16T17:30:00Z'
options:
- insight_type: late_payment
option: minimum_days_late_threshold
value: '3'
- insight_type: late_payment
option: minimum_value_threshold
value: '100.00'
/insights/v1/actionable/spending/{type}/{id}/details:
get:
tags:
- Retrieve Actionable Insights
summary: Retrieve Spending Actionable Insight Details
description: |
Retrieve insight-specific details and transaction and account data responsible for the triggered income insight of the given type and ID.
> 📘 Note:
>
> For more information about Actionable Insights, please refer to our [guide](https://docs.thisisbud.com/docs/actionable-insights).
operationId: insights_v1_actionable_spending_details_get
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/SpendingInsightType'
- $ref: '#/components/parameters/InsightID'
- $ref: '#/components/parameters/LatePaymentMinimumValueThreshold'
- $ref: '#/components/parameters/LatePaymentMinimumDaysLateThreshold'
- $ref: '#/components/parameters/RegularPaymentChangedMinimumAbsoluteChangeThreshold'
- $ref: '#/components/parameters/RegularPaymentChangedMinimumPercentageChangeThreshold'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SpendingInsightsDataResponse'
example:
operation_id: insights_v1_actionable_spending_details_get
data:
id: late_payment_8789764a-df2f-4589-b550-00bcd0e9cb2c
type: late_payment
caused_by:
accounts:
- account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
currency: GBP
holder:
name: David Smith
relationship: unknown
account_name: My Current Account
account_type: current_account
usage_type: personal
provider: BankOfBud
identifiers:
uk_sort_code: '126432'
uk_account_number: '31510604'
balances:
- date: '2023-05-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: interim_booked
credit_debit_indicator: credit
- date: '2023-05-12T00:00:00Z'
amount:
value: '3552.61'
currency: GBP
type: expected
credit_debit_indicator: credit
credit_lines:
- date: '2023-05-12T00:00:00Z'
type: credit
amount:
value: '1000.00'
currency: GBP
transactions:
- transaction_id: a_transaction_id
account_id: ee7a2d6a-2baa-461a-aca2-844e88a3f3e7
provider: a_bank_account_provider
description: MORTGAGE
credit_debit_indicator: debit
status: booked
suggested_description: mortgage
amount:
value: '1400.00'
currency: GBP
date_time: '2023-05-05T10:00:00Z'
enrichments:
categories:
l1:
slug: mortgage_and_rent
confidence: '0.99'
l2:
slug: mortgage
confidence: '0.98'
regularity:
frequency: monthly
confidence: '0.99'
predicted_date_times:
- '2023-05-10T10:00:00Z'
details:
days_late: 6
expected_date_time: '2023-05-10T10:00:00Z'
metadata:
from: '2022-11-01T00:00:00Z'
to: '2023-05-16T17:30:00Z'
options:
- insight_type: late_payment
option: minimum_days_late_threshold
value: '3'
- insight_type: late_payment
option: minimum_value_threshold
value: '10.00'
'404':
description: Insight not found. This can occur if the returned insight was invalidated by an account refresh or other change to customer data.
/insights/v1/custom/manage:
post:
tags:
- Custom Insights
summary: Create new custom insight
description: |
Create a custom insight to be applied to all customers upon ingestion or refresh of transactions
security:
- OAuth2: []
operationId: custom_insight_v1_manage_post
parameters:
- $ref: '#/components/parameters/ClientId'
requestBody:
required: true
content:
application/json:
schema:
required:
- query
properties:
query:
type: string
description: |
A valid budql query representing the desired insight, see Custom Insights Guide for more details.
example: INFER risky_spender FROM transactions WHERE category_l2 = "crypto_platform_incoming"
active:
type: boolean
description: Whether the insight is 'active' or not, defaults to true.
responses:
'200':
description: OK
content:
application/json:
schema:
required:
- operation_id
- data
properties:
operation_id:
type: string
data:
type: object
required:
- custom_insight_id
properties:
custom_insight_id:
type: string
format: uuid
example:
operation_id: custom_insight_v1_manage_post
data:
custom_insight_id: 123e4567-e89b-12d3-a456-426655440000
'400':
description: The request contained an invalid payload, in this case often a syntax error in the query.
5XX:
description: An unexpected error occurred on the server side.
get:
tags:
- Custom Insights
summary: List existing custom insights
description: |
Retrieve a list of created custom insights, if they are currently active, and when they were created
deprecated: false
security:
- OAuth2: []
operationId: custom_insight_v1_manage_get
parameters:
- $ref: '#/components/parameters/ClientId'
responses:
'200':
description: OK
content:
application/json:
schema:
required:
- operation_id
- data
properties:
operation_id:
type: string
data:
type: array
items:
type: object
required:
- custom_insight_id
properties:
custom_insight_id:
type: string
format: uuid
description: A uuid for the query
identifier:
type: string
description: A human readable identifier set in the query INFER FROM ...
query:
type: string
description: The budql query representing the custom insight
created_at:
type: string
format: date-time
active:
type: boolean
description: whether the insight is 'active' or not
example:
operation_id: custom_insight_v1_manage_get
data:
- custom_insight_id: 123e4567-e89b-12d3-a456-426655440000
identifier: risky_spender
query: INFER risky_spender FROM transactions WHERE category_l2 = "crypto_platform_incoming"
created_at: '2023-10-20T13:36:58Z'
'400':
description: Malformed request
5XX:
description: An unexpected error occurred on the server side
/insights/v1/custom/detail/{custom_insight_id}:
get:
tags:
- Custom Insights
summary: Detail the transactions used to generate a custom insight
description: |
This endpoint will return some transactions used to determine the custom insight.
More specifically it will return transactions filtered for in the WHERE expression of the custom insight query.
deprecated: false
security:
- OAuth2: []
operationId: custom_insight_v1_detail_get
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- $ref: '#/components/parameters/PathCustomInsightID'
responses:
'200':
description: OK
content:
application/json:
schema:
required:
- operation_id
- data
properties:
operation_id:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
metadata:
type: object
properties:
created_at:
type: string
description: The time when the profile was last built, and this insight was generated.
results:
type: integer
description: The number of transactions returned.
example:
operation_id: custom_insight_v1_detail_get
data:
- transaction_id: fbdc28e82f0f137586a526a88ec4a6be
account_id: 5bd9ecaf31fc2d5172fd89cb61b89fc6
provider: BankOfBud
description: paypal* specialty coffee
credit_debit_indicator: debit
status: booked
suggested_description: Specialty Coffee Supplier Ltd.
suggested_logo: http://url/specialty_coffee_supplier_logo.jpeg
amount:
value: '10.99'
currency: GBP
date_time: '2022-05-28T10:00:00Z'
posted_date_time: '2022-05-29T00:00:00Z'
value_date_time: '2022-05-29T00:00:00Z'
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
tokens:
- value: speciality coffee
confidence: '0.98'
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
processor:
id: 18f63293-0217-4520-bbf0-071dca7a9d04
slug: paypal
display_name: PayPal
logo: http://url/paypal_logo.jpeg
tokens:
- value: paypal
confidence: '0.92'
regularity:
frequency: monthly
predicted_date_times:
- '2022-06-28T15:00:00Z'
- '2022-07-28T15:00:00Z'
- '2022-08-28T15:00:00Z'
group_label: a_group_id
transaction_types:
- card
- debit
names:
- jane doe
tags:
- regular-transaction
- transaction_id: a2294cebb45d2a6e0cfc70d270988d8c
account_id: 37c633a71237b9a8282e09587109668e
provider: BankOfBud
description: Tesco 2956 London GBR
credit_debit_indicator: debit
status: booked
suggested_description: Tesco
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/17ac2742-8c93-4c11-a01f-17ad65b950ce/v2/tesco.jpeg
amount:
value: '50.23'
currency: GBP
date_time: '2022-05-26T10:00:00Z'
posted_date_time: '2022-05-27T00:00:00Z'
value_date_time: '2022-05-27T00:00:00Z'
enrichments:
categories:
l1:
slug: eating_out
confidence: '0.99'
l2:
slug: cafes_and_eating_out
confidence: '0.98'
merchant:
id: 0980cf54-6052-4527-84ff-e6f9b169884f
slug: tesco_stores
display_name: Tesco
logo: http://url/tesco_stores_logo.jpeg
tokens:
- value: tesco
confidence: '0.96'
location:
address:
address_lines:
- '180'
- Shepherds Bush Rd
- London
- W6 7NL
- United Kingdom
street_address: Shepherds Bush Rd
city: London
postal_code: W6 7NL
country: United Kingdom
geolocation:
longitude: 51.497678
latitude: -0.223766
transaction_types:
- card
- debit
metadata:
results: 2
created_at: '2023-11-23T10:41:55Z'
'404':
description: Custom insight doesn't exist, or there has been no profile built for this customer
5XX:
description: An unexpected error occurred on the server side
/insights/v1/custom/manage/{custom_insight_id}:
delete:
tags:
- Custom Insights
summary: Delete existing custom insight
description: |
Permanently deletes a custom insight query
deprecated: false
security:
- OAuth2: []
operationId: custom_insight_v1_manage_delete
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/PathCustomInsightID'
responses:
'204':
description: OK
'404':
description: Custom insight doesn't exist, thus cannot be deleted
5XX:
description: An unexpected error occurred on the server side
patch:
tags:
- Custom Insights
summary: Update existing custom insight
deprecated: false
description: |
Patches a custom insight, updating the query, or setting it to active/inactive
security:
- OAuth2: []
operationId: custom_insight_v1_manage_patch
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/PathCustomInsightID'
requestBody:
required: true
content:
application/json:
schema:
properties:
query:
type: string
description: |
A valid budql query representing the desired insight, see Custom Insights Guide for more details,
defaults to the value of the existing insight.
example: INFER risky_spender FROM transactions WHERE category_l2 = "crypto_platform_incoming"
active:
type: boolean
description: whether the insight is 'active' or not, defaults to the value of the existing insight
responses:
'204':
description: OK
'400':
description: The request contained an invalid payload, in this case often a syntax error in the query.
'404':
description: Custom insight doesn't exist, thus cannot be patched
5XX:
description: An unexpected error occurred on the server side
/insights/v1/custom/manage/all:
delete:
tags:
- Custom Insights
summary: Delete all existing custom insights
description: |
Permanently deletes all custom insight queries
deprecated: false
security:
- OAuth2: []
operationId: custom_insight_v1_manage_delete_all
parameters:
- $ref: '#/components/parameters/ClientId'
responses:
'204':
description: OK
5XX:
description: An unexpected error occurred on the server side
/insights/v1/custom/profile:
post:
tags:
- Custom Insights
summary: Build custom insights profile
description: |
Manually builds a custom insight profile for a customer, is automatically called after successful ingestion and enrichment.
deprecated: false
security:
- OAuth2: []
operationId: custom_insight_v1_profile_post
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
- in: header
name: X-Now
required: false
schema:
type: string
format: date-time
example: '2000-01-01T00:00:00.05Z'
responses:
'204':
description: OK
get:
tags:
- Custom Insights
summary: Retrieve custom insights profile
description: |
Lists the insights which applied to a customer at \'created_at\'.
To recompute make a call to Build custom insights profile.
deprecated: false
security:
- OAuth2: []
operationId: custom_insight_v1_profile_get
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
- $ref: '#/components/parameters/CustomerSecret'
responses:
'200':
description: OK
content:
application/json:
schema:
required:
- operation_id
- data
properties:
operation_id:
type: string
data:
type: array
items:
type: object
required:
- custom_insight_id
- identifier
- link
- created_at
properties:
custom_insight_id:
type: string
format: uuid
description: A uuid for the query used to generate the insight
identifier:
type: string
description: A human readable identifier set in the query INFER FROM ...
created_at:
type: string
format: date-time
link:
description: link to a detail view of the insight
type: string
example:
operation_id: custom_insight_v1_profile_get
data:
- identifier: always_true
custom_insight_id: 19ebab24-9c73-4802-b5d2-c401f3558d8d
link: insights/v1/custom/detail/19ebab24-9c73-4802-b5d2-c401f3558d8d
created_at: '2021-08-11T14:00:00Z'
/widget/v1/summary/url:
post:
tags:
- Frontend Widgets
summary: Generate Card Summary URL
description: Generates customer's weekly summary insights.
deprecated: false
security:
- OAuth2: []
operationId: insights_v1_summary_url_post
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateCardSummaryURLRequest'
responses:
'201':
description: Successful response containing the Card Summary URL and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateCardSummaryURLResponse'
example:
operation_id: insights_v1_summary_url_post
data:
url: https://widgets.thisisbud.com/summary/953ea9c1-faee-4daf-9790-4cfd649f66f7?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI5MWQ5ZmRjZC03MjI3LTQyMTAtYWNiYi0xY2VhNDY0OTA0NzAiLCJhdWQiOlsiaHR0cHM6Ly93aWRnZXQtcHJveHkudGhpc2lzYnVkLmNvbSJdLCJjdXN0b21lcl9pZCI6IjY5Yjg4YmM3LTI5OGYtNDY2NC04NWQ5LWM5YWJiZTM5NDg1NiIsImV4cCI6MTczMjY1MTIwMCwic3ViIjoiMTIzNDU2Nzg5MCIsIm9yZ19pZCI6IjdmMDU5OTUwLWNjYTctNGZiMS1hZTQyLTc1NzdkNzA5N2NmNyIsIm9yZ19zbHVnIjoiYnVkIn0.0ufJFC16yNps0npeOp60dC97GP6er2t1zuQcQ11IHp8
metadata:
sufficient_data: true
number_of_insights: 5
summary_to: '2023-05-16T17:30:00Z'
summary_from: '2023-05-09T17:30:00Z'
'400':
description: Not supported summary type was requested
'401':
description: Customer doesn't exist
5XX:
description: An unexpected error occurred on the server side
/widget/v1/financial-calendar/url:
post:
tags:
- Frontend Widgets
summary: Generate Financial Calendar URL
description: Generates a URL to access the customer's financial calendar.
deprecated: false
security:
- OAuth2: []
operationId: insights_v1_financial_calendar_url_post
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateFinancialCalendarURLRequest'
responses:
'201':
description: Successful response containing Financial Calendar URL and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateFinancialCalendarURLResponse'
example:
operation_id: insights_v1_financial_calendar_url_post
data:
url: https://widgets.thisisbud.com/financial-calendar?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI5MWQ5ZmRjZC03MjI3LTQyMTAtYWNiYi0xY2VhNDY0OTA0NzAiLCJhdWQiOlsiaHR0cHM6Ly93aWRnZXQtcHJveHkudGhpc2lzYnVkLmNvbSJdLCJjdXN0b21lcl9pZCI6IjY5Yjg4YmM3LTI5OGYtNDY2NC04NWQ5LWM5YWJiZTM5NDg1NiIsImV4cCI6MTczMjY1MTIwMCwic3ViIjoiMTIzNDU2Nzg5MCIsIm9yZ19pZCI6IjdmMDU5OTUwLWNjYTctNGZiMS1hZTQyLTc1NzdkNzA5N2NmNyIsIm9yZ19zbHVnIjoiYnVkIn0.0ufJFC16yNps0npeOp60dC97GP6er2t1zuQcQ11IHp8
metadata:
sufficient_data: true
'400':
description: Bad Request
5XX:
description: An unexpected error occurred on the server side
/widget/v1/balances-over-time/url:
post:
tags:
- Frontend Widgets
summary: Generate Balances Over Time URL
description: Generates a URL to access the customer's balances over time.
deprecated: false
security:
- OAuth2: []
operationId: insights_v1_balances_over_time_url_post
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateBalancesOverTimeURLRequest'
responses:
'201':
description: Successful response containing Balances Over Time URL and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateBalancesOverTimeURLResponse'
example:
operation_id: insights_v1_balances_over_time_url_post
data:
url: https://widgets.thisisbud.com/balances-over-time?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI5MWQ5ZmRjZC03MjI3LTQyMTAtYWNiYi0xY2VhNDY0OTA0NzAiLCJhdWQiOlsiaHR0cHM6Ly93aWRnZXQtcHJveHkudGhpc2lzYnVkLmNvbSJdLCJjdXN0b21lcl9pZCI6IjY5Yjg4YmM3LTI5OGYtNDY2NC04NWQ5LWM5YWJiZTM5NDg1NiIsImV4cCI6MTczMjY1MTIwMCwic3ViIjoiMTIzNDU2Nzg5MCIsIm9yZ19pZCI6IjdmMDU5OTUwLWNjYTctNGZiMS1hZTQyLTc1NzdkNzA5N2NmNyIsIm9yZ19zbHVnIjoiYnVkIn0.0ufJFC16yNps0npeOp60dC97GP6er2t1zuQcQ11IHp8
metadata:
sufficient_data: true
'400':
description: Bad Request
5XX:
description: An unexpected error occurred on the server side
/widget/v1/recurring-and-forecasted-transactions/url:
post:
tags:
- Frontend Widgets
summary: Generate Recurring and Forecasted Transactions URL
description: Generates a URL to access the customer's recurring and forecasted transactions.
deprecated: false
security:
- OAuth2: []
operationId: insights_v1_recurring_and_forecasted_transactions_url_post
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateRecurringAndForecastedTransactionsURLRequest'
responses:
'201':
description: Successful response containing Recurring and Forecasted Transactions URL and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateRecurringAndForecastedTransactionsURLResponse'
example:
operation_id: insights_v1_recurring_and_forecasted_transactions_url_post
data:
url: https://widgets.thisisbud.com/recurring-and-forecasted-transactions?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI5MWQ5ZmRjZC03MjI3LTQyMTAtYWNiYi0xY2VhNDY0OTA0NzAiLCJhdWQiOlsiaHR0cHM6Ly93aWRnZXQtcHJveHkudGhpc2lzYnVkLmNvbSJdLCJjdXN0b21lcl9pZCI6IjY5Yjg4YmM3LTI5OGYtNDY2NC04NWQ5LWM5YWJiZTM5NDg1NiIsImV4cCI6MTczMjY1MTIwMCwic3ViIjoiMTIzNDU2Nzg5MCIsIm9yZ19pZCI6IjdmMDU5OTUwLWNjYTctNGZiMS1hZTQyLTc1NzdkNzA5N2NmNyIsIm9yZ19zbHVnIjoiYnVkIn0.0ufJFC16yNps0npeOp60dC97GP6er2t1zuQcQ11IHp8
metadata:
sufficient_data: true
'400':
description: Bad Request
5XX:
description: An unexpected error occurred on the server side
/widget/v1/spending-analysis/url:
post:
tags:
- Frontend Widgets
security:
- OAuth2: []
operationId: insights_v1_spending_analysis_url_post
summary: Generate Spending Analysis URL
description: Generates a URL to access the customer's spending analysis.
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateSpendingAnalysisURLRequest'
responses:
'201':
description: Successful response containing Spending Analysis URL and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateSpendingAnalysisURLResponse'
example:
operation_id: insights_v1_spending_analysis_url_post
data:
url: https://widgets.thisisbud.com/spending-analysis?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI5MWQ5ZmRjZC03MjI3LTQyMTAtYWNiYi0xY2VhNDY0OTA0NzAiLCJhdWQiOlsiaHR0cHM6Ly93aWRnZXQtcHJveHkudGhpc2lzYnVkLmNvbSJdLCJjdXN0b21lcl9pZCI6IjY5Yjg4YmM3LTI5OGYtNDY2NC04NWQ5LWM5YWJiZTM5NDg1NiIsImV4cCI6MTczMjY1MTIwMCwic3ViIjoiMTIzNDU2Nzg5MCIsIm9yZ19pZCI6IjdmMDU5OTUwLWNjYTctNGZiMS1hZTQyLTc1NzdkNzA5N2NmNyIsIm9yZ19zbHVnIjoiYnVkIn0.0ufJFC16yNps0npeOp60dC97GP6er2t1zuQcQ11IHp8
metadata:
sufficient_data: true
'400':
description: Bad Request
5XX:
description: An unexpected error occurred on the server side
/widget/v1/spending-budgets/url:
post:
tags:
- Frontend Widgets
security:
- OAuth2: []
operationId: insights_v1_spending_budgets_url_post
summary: Generate Spending Budgets URL
description: Generates a URL to access the customer's spending budgets.
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateSpendingBudgetsURLRequest'
responses:
'201':
description: Successful response containing Spending Budgets URL and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateSpendingBudgetsURLResponse'
example:
operation_id: insights_v1_spending_budgets_url_post
data:
url: https://widgets.thisisbud.com/spending-budgets?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI5MWQ5ZmRjZC03MjI3LTQyMTAtYWNiYi0xY2VhNDY0OTA0NzAiLCJhdWQiOlsiaHR0cHM6Ly93aWRnZXQtcHJveHkudGhpc2lzYnVkLmNvbSJdLCJjdXN0b21lcl9pZCI6IjY5Yjg4YmM3LTI5OGYtNDY2NC04NWQ5LWM5YWJiZTM5NDg1NiIsImV4cCI6MTczMjY1MTIwMCwic3ViIjoiMTIzNDU2Nzg5MCIsIm9yZ19pZCI6IjdmMDU5OTUwLWNjYTctNGZiMS1hZTQyLTc1NzdkNzA5N2NmNyIsIm9yZ19zbHVnIjoiYnVkIn0.0ufJFC16yNps0npeOp60dC97GP6er2t1zuQcQ11IHp8
metadata:
sufficient_data: true
'400':
description: Bad Request
5XX:
description: An unexpected error occurred on the server side
/widget/v1/savings-goals/url:
post:
tags:
- Frontend Widgets
security:
- OAuth2: []
operationId: insights_v1_savings_goals_url_post
summary: Generate Savings Goals URL
description: Generates a URL to access the customer's savings goals.
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateSavingsGoalsURLRequest'
responses:
'201':
description: Successful response containing Savings Goals URL and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateSavingsGoalsURLResponse'
example:
operation_id: insights_v1_savings_goals_url_post
data:
url: https://widgets.thisisbud.com/savings-goals?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI5MWQ5ZmRjZC03MjI3LTQyMTAtYWNiYi0xY2VhNDY0OTA0NzAiLCJhdWQiOlsiaHR0cHM6Ly93aWRnZXQtcHJveHkudGhpc2lzYnVkLmNvbSJdLCJjdXN0b21lcl9pZCI6IjY5Yjg4YmM3LTI5OGYtNDY2NC04NWQ5LWM5YWJiZTM5NDg1NiIsImV4cCI6MTczMjY1MTIwMCwic3ViIjoiMTIzNDU2Nzg5MCIsIm9yZ19pZCI6IjdmMDU5OTUwLWNjYTctNGZiMS1hZTQyLTc1NzdkNzA5N2NmNyIsIm9yZ19zbHVnIjoiYnVkIn0.0ufJFC16yNps0npeOp60dC97GP6er2t1zuQcQ11IHp8
metadata:
sufficient_data: true
'400':
description: Bad Request
5XX:
description: An unexpected error occurred on the server side
/widget/v1/intelligent-search/url:
post:
tags:
- Frontend Widgets
summary: Generate Intelligent Search Widget URL
operationId: insights_v1_intelligent_search_url_post
description: Generates a URL to a frontend to allow searching a customers transactions.
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateIntelligentSearchURLRequest'
responses:
'201':
description: Successful response containing Intelligent Search URL and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateIntelligentSearchURLResponse'
example:
operation_id: insights_v1_intelligent_search_url_post
data:
url: https://widgets.thisisbud.com/intelligent-search/953ea9c1-faee-4daf-9790-4cfd649f66f7?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI5MWQ5ZmRjZC03MjI3LTQyMTAtYWNiYi0xY2VhNDY0OTA0NzAiLCJhdWQiOlsiaHR0cHM6Ly93aWRnZXQtcHJveHkudGhpc2lzYnVkLmNvbSJdLCJjdXN0b21lcl9pZCI6IjY5Yjg4YmM3LTI5OGYtNDY2NC04NWQ5LWM5YWJiZTM5NDg1NiIsImV4cCI6MTczMjY1MTIwMCwic3ViIjoiMTIzNDU2Nzg5MCIsIm9yZ19pZCI6IjdmMDU5OTUwLWNjYTctNGZiMS1hZTQyLTc1NzdkNzA5N2NmNyIsIm9yZ19zbHVnIjoiYnVkIn0.0ufJFC16yNps0npeOp60dC97GP6er2t1zuQcQ11IHp8
metadata:
sufficient_data: true
'401':
description: An unauthenticated request was received.
5XX:
description: An unexpected error occurred on the server side
/widget/v1/accounts/url:
post:
tags:
- Frontend Widgets
summary: Generate Accounts URL
description: Generates a URL to access the customer's account.
deprecated: false
security:
- OAuth2: []
operationId: insights_v1_accounts_url_post
parameters:
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CustomerIdempotentIdentifier'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateAccountsURLRequest'
responses:
'201':
description: Successful response containing accounts URL and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateAccountsURLResponse'
example:
operation_id: insights_v1_accounts_url_post
data:
url: https://widgets.thisisbud.com/accounts?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI5MWQ5ZmRjZC03MjI3LTQyMTAtYWNiYi0xY2VhNDY0OTA0NzAiLCJhdWQiOlsiaHR0cHM6Ly93aWRnZXQtcHJveHkudGhpc2lzYnVkLmNvbSJdLCJjdXN0b21lcl9pZCI6IjY5Yjg4YmM3LTI5OGYtNDY2NC04NWQ5LWM5YWJiZTM5NDg1NiIsImV4cCI6MTczMjY1MTIwMCwic3ViIjoiMTIzNDU2Nzg5MCIsIm9yZ19pZCI6IjdmMDU5OTUwLWNjYTctNGZiMS1hZTQyLTc1NzdkNzA5N2NmNyIsIm9yZ19zbHVnIjoiYnVkIn0.0ufJFC16yNps0npeOp60dC97GP6er2t1zuQcQ11IHp8
metadata:
sufficient_data: true
'400':
description: Bad Request
5XX:
description: An unexpected error occurred on the server side
components:
securitySchemes:
Basic:
type: http
scheme: basic
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: /v1/oauth/token
scopes: {}
description: |
Authentication flow:
1. Perform OAuth2 Client Credentials authentication using API Credentials (`client_id`,`client_secret`) to obtain an `access_token` against `/v1/oauth/token` endpoint,
2. Use `access_token` as Bearer Authorisation for every other API request,
3. Include `X-Client-Id` (=client_id) within the header of every API request,
4. Note that some of the requests may also require `X-Customer-Id` to be provided within the request header.
### Examples
Obtain OAuth2 `access_token` and `refresh_token` using `grant_type=client_credentials` and HTTP Basic auth header
```
curl --basic --user {{client_id}}:{{client_secret}} \
-X POST https://api-sandbox.thisisbud.com/v1/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d grant_type=client_credentials
```
Successful response:
```
{
"operation_id": "oauth_token_post",
"data": {
"access_token": "dd0c17e3fd6d2ce94aa091257a3ea393b4f9b5cf3d3e998f07dc9826da86ff15",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "fac32cca7559d9f6e8f1dfe9a99c71fa1dcfeb482bedf287d7934d2667ae54b3"
}
}
```
Refresh `access_token` token using `refresh_token` against `/v1/oauth/token` endpoint with `grant_type=refresh_token`
```
curl -X POST \
https://api-sandbox.thisisbud.com/v1/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'X-Client-Id: {{client_id}}' \
-d 'grant_type=refresh_token&refresh_token={{refresh_token}}'
```
Successful response:
```
{
"operation_id": "oauth_token_post",
"data": {
"access_token": "cc0c17e3fd6d2ce94aa091257a3ea393b4f9b5cf3d3e998f07dc9826da86ff94",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "ffc30cca7559d9f6e8f1dfe9a99c71fa1dcfeb482bedf287d7934d2667ae54b3"
}
}
```
schemas:
RetrieveAuthTokenResponse:
title: Retrieve Auth Token Response
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- oauth_token_create
data:
type: object
required:
- access_token
- token_type
- expires_in
- refresh_token
properties:
access_token:
type: string
description: A short-lived token that is used to authenticate requests to Bud endpoints.
token_type:
type: string
description: The type of token provided in the `access_token` field (typically `Bearer`).
expires_in:
type: integer
description: The amount of time (in seconds) in which the `access_token` will expire.
refresh_token:
type: string
description: A long-lived token that can be used to obtain a new `access_token` when the current `access_token` expires.
Transaction:
title: Transaction
type: object
description: A financial transaction
required:
- transaction_id
- account_id
- description
- amount
- credit_debit_indicator
- status
- date_time
- suggested_description
properties:
transaction_id:
type: string
description: Unique identifier for the transaction. May be mutable depending on original ingestion source.
account_id:
type: string
description: Identifier for the account associated with the transaction.
provider:
type: string
description: Name of the transaction source provider. Optional as it may not have been supplied when using first party data.
description:
type: string
description: Description of the transaction.
credit_debit_indicator:
type: string
description: Credit/Debit Indicator
enum:
- credit
- debit
status:
type: string
description: |
Status of the transaction. Defaults to booked.
Note: declined transactions are only available for transactions ingested by First Party Ingestion endpoints.
enum:
- booked
- pending
- declined
suggested_description:
type: string
description: The description Bud suggests client apps show for a given transaction.
suggested_logo:
type: string
description: The logo Bud suggests client apps show for a given transaction.
transaction_type:
$ref: '#/components/schemas/BudTransactionType'
amount:
$ref: '#/components/schemas/BudAmount'
date_time:
type: string
description: Date that the transaction occured compliant with RFC3339.
posted_date_time:
deprecated: true
type: string
description: Date the assets involved in the transaction transferred compliant with RFC3339. For credits this is the date that the asset becomes available, for debits this is the date that the asset ceased to be available
value_date_time:
type: string
description: Date the assets involved in the transaction transferred compliant with RFC3339. For credits this is the date that the asset becomes available, for debits this is the date that the asset ceased to be available
enrichments:
$ref: '#/components/schemas/Enrichments'
merchant_category_code:
type: string
description: Merchant category code conforming to ISO 18245, related to the type of services or goods the merchant provides for the transaction.
running_balance:
description: The running balance for the account that the transaction takes place against
title: Standard Bud Amount
type: object
required:
- value
- currency
properties:
value:
$ref: '#/components/schemas/BudMonetaryValue'
currency:
$ref: '#/components/schemas/BudCurrency'
counterparty:
type: object
description: An object containing details of the counterparty in this transaction
properties:
name:
type: string
description: The name of the counterparty involved in this transaction.
identifier:
type: string
description: An identifier for the account of the other party
tags:
type: array
description: |
A list of potential tags associated with the transaction after contextual enrichment, which can be used for filtering.
Region and client specific.
| Value | Description |
|:------------------------|:----------------------------------------------------------|
| `benefit` | A government/non-profit benefit transaction |
| `debt-collection` | A transaction associated with a known debt-collector |
| `loan` | A transaction associated with a loan |
| `hcst` | A transaction associated with a high cost short term loan |
| `income` | A transaction associated with income |
| `pending` | A transaction which has not been booked |
| `regular-transaction` | A transaction predicted to occur with a regular frequency |
| `subscription` | A transaction associated with a subscription service |
| `online` | A transaction associated with an online merchant |
| `bill` | A transaction associated with an bill payment |
| `internal-transfer` | A transaction between a customers accounts |
items:
type: string
client_attributes:
$ref: '#/components/schemas/ClientAttributes'
ClientAttributes:
title: Client Attributes
type: object
description: |
An optional map of key-value string pairs that allows clients to attach arbitrary metadata to the transaction.
This field can be used to store any relevant information specific to the client's needs, such as:
These attributes can be added using the [Ingest Transactions](#operation/v2_ingest_transactions_post) endpoint.
properties:
key:
type: string
description: An arbitrary key-value pair for the client attribute.
Enrichments:
title: Enrichments
type: object
description: Contextual enrichments associated with a Transaction
properties:
categories:
$ref: '#/components/schemas/Categories'
merchant:
$ref: '#/components/schemas/Merchant'
processor:
$ref: '#/components/schemas/Processor'
regularity:
$ref: '#/components/schemas/Regularity'
location:
$ref: '#/components/schemas/Location'
transaction_types:
type: array
description: Transaction types associated with the transaction
items:
type: string
names:
type: array
description: Names that were detected in the transaction description
items:
type: string
Categories:
title: Categories
type: object
description: |
Categories enrichment associated with a Transaction, as generated by Bud's artificial intelligence models. Currently two levels of category are supported, with `l1` being a coarse-grained category level and `l2` being more refined.
properties:
l1:
$ref: '#/components/schemas/Category'
description: Level 1 Category
l2:
$ref: '#/components/schemas/Category'
description: Level 2 Category
Category:
title: Category
type: object
description: Category associated with a Transaction
required:
- slug
- confidence
properties:
slug:
type: string
description: Unique human readable identifier of the category. Not subject to version control.
confidence:
type: string
description: Degree of belief of correct assignment, expressed as a probability.
Merchant:
title: Merchant
type: object
description: |
Merchant enrichment associated with a Transaction, as generated using a combination of Bud's artificial intelligence models and database of known merchants.
properties:
id:
type: string
description: UUID corresponding to the merchant, if available. Subject to version control.
slug:
type: string
description: Unique human readable identifier of the merchant. Not subject to version control.
display_name:
type: string
description: UI friendly display name for the merchant.
logo:
type: string
description: URL supplying merchant logo, if available.
tokens:
type: array
description: |
A list of tokens calculated from the transaction model, used to identify the Merchant. This list is often present even if the merchant details (id, slug, disply_name, logo) are not returned.
items:
$ref: '#/components/schemas/Token'
website:
type: string
description: URL supplying merchant website, if available.
tags:
type: array
items:
type: string
description: A list of tags describing the merchant
Processor:
title: Processor
type: object
description: |
Processor enrichment associated with a Transaction, as generated using a combination of Bud's artificial intelligence models and database of known payment processors.
properties:
id:
type: string
description: UUID corresponding to the processor, if available. Subject to version control.
slug:
type: string
description: Unique human readable identifier of the processor. Not subject to version control.
display_name:
type: string
description: UI friendly display name for the processor.
logo:
type: string
description: URL supplying processor logo, if available.
tokens:
type: array
description: |
A list of tokens calculated from the transaction model, used to identify the Merchant. This list is often present even if the merchant details (id, slug, disply_name, logo) are not returned.
items:
$ref: '#/components/schemas/Token'
website:
type: string
description: URL supplying merchant website, if available.
Regularity:
title: Regularity
type: object
description: |
Regularity enrichment associated with a Transaction, as generated by Bud's artificial intelligence models. Transactions that are similar and have a known frequency will all have the same regularity enrichment.
properties:
frequency:
type: string
description: Detected frequency of the Transaction.
enum:
- unknown
- daily
- weekly
- biweekly
- monthly
- quarterly
predicted_date_times:
type: array
description: Expected date times for the Transaction to repeat.
items:
type: string
group_label:
type: string
description: Unique label applied to multiple transactions in the same group.
Location:
title: Location
type: object
description: Location enrichment associated with a Transaction
properties:
address:
type: object
description: The address where the transaction occurred. The level of detail depends on the resolution with which we are able to detect the transaction location.
properties:
address_lines:
type: array
description: A list of all the address lines detected for the transaction. This could be anything from a full street address down to just the region.
items:
type: string
street_address:
type: string
description: The street address where the transaction occurred. Typically this will consist of the street number and street name with an optional suite.
city:
type: string
description: The city or town where the transaction occurred.
region:
type: string
description: The county or region where the transaction occurred.
postal_code:
type: string
description: The postcode where the transaction occurred.
country:
type: string
description: |
The ISO 3166-1 alpha-2 country code representing the country where the transaction occurred.
If a location could not be determined, but a `country_code` was supplied in the ingestion request; that value will be reflected here.
geolocation:
type: object
description: The geolocation where the transaction occurred. This is only available if we are able to narrow down the transaction location to an exact match.
properties:
latitude:
type: number
format: double
description: The latitudinal position where the transaction occurred.
longitude:
type: number
format: double
description: The longitudinal position where the transaction occurred.
tokens:
type: array
description: A list of substrings from the description identified as being relevant to the transaction location.
items:
type: string
Token:
title: Token
type: object
description: The token item.
required:
- value
- confidence
properties:
value:
type: string
confidence:
type: string
description: Degree of belief of correct assignment, expressed as a probability.
ListTransactionsResponse:
title: Retrieve Transactions Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- v2_transactions_get
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
metadata:
type: object
required:
- results
properties:
results:
type: integer
description: The number of results returned.
updated_after:
type: string
description: The timestamp used to filter results in the query parameter `updated_after`. Only transactions updated after this time are returned.
deleted:
type: array
description: |
The `deleted` field is only present when `updated_after` is supplied. It shows the transaction IDs that have been deleted from Bud's platform since the `updated_after` timestamp.
items:
type: object
required:
- transaction_id
- at
properties:
transaction_id:
type: string
description: The ID of a transaction that has been deleted.
at:
type: string
description: The timestamp when the transaction was deleted.
next_page_token:
type: string
description: The token required to retrieve the next page of results. Will be omitted if no next page exists.
TransactionForSyncIngest:
title: Transaction
type: object
description: A financial transaction
required:
- transaction_id
- account_id
- description
- amount
- credit_debit_indicator
- status
- date_time
- suggested_description
properties:
transaction_id:
type: string
description: Unique identifier for the transaction. May be mutable depending on original ingestion source.
account_id:
type: string
description: Identifier for the account associated with the transaction.
description:
type: string
description: Description of the transaction.
credit_debit_indicator:
type: string
description: Credit/Debit Indicator
enum:
- credit
- debit
status:
type: string
description: Status of the transaction. Defaults to booked.
enum:
- booked
- pending
- declined
suggested_description:
type: string
description: The description Bud suggests client apps show for a given transaction.
suggested_logo:
type: string
description: The logo Bud suggests client apps show for a given transaction.
transaction_type:
$ref: '#/components/schemas/BudTransactionType'
amount:
$ref: '#/components/schemas/BudAmount'
date_time:
type: string
description: Date of the transaction compliant with RFC3339.
value_date_time:
type: string
description: Date the assets involved in the transaction transferred compliant with RFC3339. For credits this is the date that the asset becomes available, for debits this is the date that the asset ceased to be available
enrichments:
$ref: '#/components/schemas/SyncEnrichments'
merchant_category_code:
type: string
description: |
A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245. An MCC is used to classify a business by the types of goods or services it provides.
tags:
type: array
description: |
A list of potential tags associated with the transaction after contextual enrichment, which can be used for filtering.
Region and client specific.
| Value | Description |
|:------------------------|:----------------------------------------------------------|
| `benefit` | A government/non-profit benefit transaction |
| `debt-collection` | A transaction associated with a known debt-collector |
| `loan` | A transaction associated with a loan |
| `hcst` | A transaction associated with a high cost short term loan |
| `income` | A transaction associated with income |
| `pending` | A transaction which has not been booked |
| `regular-transaction` | A transaction predicted to occur with a regular frequency |
| `subscription` | A transaction associated with a subscription service |
| `online` | A transaction associated with an online merchant |
items:
type: string
SyncEnrichments:
title: Enrichments
type: object
description: Contextual enrichments associated with a Transaction
properties:
categories:
$ref: '#/components/schemas/Categories'
merchant:
$ref: '#/components/schemas/Merchant'
processor:
$ref: '#/components/schemas/Processor'
location:
$ref: '#/components/schemas/Location'
transaction_types:
type: array
description: Transaction types associated with the transaction
items:
type: string
names:
type: array
description: Names that were detected in the transaction description
items:
type: string
SimilarTransactionsResponse:
title: Retrieve Similar Transactions Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- corrections_v2_similar_categories_get
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
metadata:
type: object
required:
- results
properties:
results:
type: integer
description: The number of results returned.
exclude_source:
type: boolean
description: Is the request transaction being excluded from the response
SimilarTransactionsIncludingMerchantsResponse:
title: Retrieve Similar Transactions including Merchants Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- corrections_v2_similar_merchants_get
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
metadata:
type: object
required:
- results
properties:
results:
type: integer
description: The number of results returned.
exclude_source:
type: boolean
description: Is the request transaction being excluded from the response
CustomerMerchantCorrectionResponse:
title: Customer Merchant Corrections Response
type: object
description: Expected response structure for the merchant corrections endpoint
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- corrections_v2_merchants_post
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
metadata:
type: object
description: Metadata associated with the merchant correction response schema
required:
- effected_transactions_count
- include_similar
- merchant_id
- transactions
properties:
effected_transactions_count:
type: number
description: The number of transaction corrected
include_similar:
type: boolean
description: Value of include_similar in the request
merchant_id:
type: string
description: Value of merchant_id in the request
transactions:
type: array
description: Value of transactions id list in the request
items:
type: string
SearchTransactionsResponseBody:
title: Search Transactions Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- search_beta_transactions_get
data:
type: object
required:
- id
- results
- suggested_searches
properties:
id:
title: Search ID
type: string
format: uuid
results:
type: array
items:
$ref: '#/components/schemas/TransactionSearchResult'
suggested_searches:
type: array
items:
$ref: '#/components/schemas/SuggestedTransactionSearch'
insight:
type: object
required:
- url
- url_delay
properties:
url:
type: string
description: The URL (relative path) to fetch the insight linked to this search
url_delay:
type: integer
format: milliseconds
description: The recomended time (in milliseconds) to wait before trying to fetch the insight.
metadata:
$ref: '#/components/schemas/TransactionSearchMetadata'
SearchTransactionsResponseBodyTransactionId:
title: Search Transactions Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- search_beta_transactions_get
data:
type: object
required:
- id
- results
- suggested_searches
properties:
id:
title: Search ID
type: string
format: uuid
results:
type: array
items:
$ref: '#/components/schemas/TransactionIdSearchResult'
suggested_searches:
type: array
items:
$ref: '#/components/schemas/SuggestedTransactionSearch'
insight:
type: object
required:
- url
- url_delay
properties:
url:
type: string
description: The URL (relative path) to fetch the insight linked to this search
url_delay:
type: integer
format: milliseconds
description: The recomended time (in milliseconds) to wait before trying to fetch the insight.
metadata:
$ref: '#/components/schemas/TransactionSearchMetadata'
SearchTransactionsInsightResponseBody:
title: Search Transactions Insight Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- search_beta_transactions_insight_get
data:
type: object
required:
- id
- status
properties:
id:
title: Search ID
type: string
format: uuid
status:
title: Insight Generation Status
description: Status of the insight generation. Once this moves from `pending` to `completed`, `content` & `transactions` will be returned.
type: string
enum:
- pending
- completed
- error
content:
type: object
required:
- text
- matched_searches
properties:
text:
title: Insight text
type: string
matched_searches:
type: array
items:
$ref: '#/components/schemas/InsightMatchedTransactionSearch'
transactions:
description: Information relating to the transactions used in calculating the insight.
type: object
required:
- url
- results
- merchants
properties:
url:
description: A path to the transactions used in calculating the insight.
type: string
results:
description: The number of transactions used in calculating the insight
type: integer
merchants:
description: The set of merchants found in the transactions,
type: array
items:
type: object
properties:
display_name:
type: string
description: UI friendly display name for the merchant.
logo:
type: string
description: URL supplying merchant logo, if available.
metadata:
$ref: '#/components/schemas/TransactionSearchInsightMetadata'
SearchInsightTransactionsResponseBody:
title: Search Insight Transactions Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- search_beta_transactions_insight_transactions_get
data:
type: object
required:
- id
- results
properties:
id:
title: Search ID
type: string
format: uuid
results:
type: array
items:
$ref: '#/components/schemas/TransactionSearchResult'
metadata:
$ref: '#/components/schemas/TransactionSearchMetadata'
SearchInsightTransactionsResponseBodyTransactionId:
title: Search Insight Transactions Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- search_beta_transactions_insight_transactions_get
data:
type: object
required:
- id
- results
properties:
id:
title: Search ID
type: string
format: uuid
results:
type: array
items:
$ref: '#/components/schemas/TransactionIdSearchResult'
metadata:
$ref: '#/components/schemas/TransactionSearchMetadata'
TransactionSearchResult:
title: Transaction Search Result
type: object
required:
- matches
- transaction
properties:
matches:
title: Matches
type: array
items:
$ref: '#/components/schemas/TransactionSearchResultMatches'
transaction:
$ref: '#/components/schemas/Transaction'
TransactionIdSearchResult:
title: Transaction ID Search Result
type: object
required:
- matches
- transaction_id
properties:
matches:
title: Matches
type: array
items:
$ref: '#/components/schemas/TransactionSearchResultMatches'
transaction_id:
type: string
description: Unique identifier for the transaction. May be mutable depending on original ingestion source.
TransactionSearchResultMatches:
type: object
required:
- type
- content
properties:
type:
$ref: '#/components/schemas/TransactionFilterType'
content:
type: string
description: the content which matched in the transaction field, to facilitate highlighting to the user
SuggestedTransactionSearch:
title: Suggested Transaction Search
type: object
required:
- filter
- url
properties:
filter:
$ref: '#/components/schemas/TransactionFilter'
url:
type: string
InsightMatchedTransactionSearch:
title: Insight Search Term
description: A search term which has been detected in the insight text. This can be exposed as an interaction for the customer using the links & text positions provided.
type: object
required:
- filter
- url
- text_positions
properties:
filter:
$ref: '#/components/schemas/TransactionFilter'
url:
type: string
text_positions:
type: array
description: All byte positions of the search term in the insight text (assuming utf-16 string encoding).
items:
type: object
description: |-
The start and end position of the search term in the text. The end position is exclusive.
E.g. "hello" in "hello world" would have start: 0, end: 5.
required:
- start
- end
properties:
start:
type: integer
end:
type: integer
TransactionFilter:
title: Transaction Filter
type: object
required:
- type
- value
- logo
properties:
type:
$ref: '#/components/schemas/TransactionFilterType'
value:
type: string
logo:
type: string
description: An icon to allow the user to distinguish between different types of filter, possibly with the same value e.g. searching for a tag of 'bills' vs 'bills' contained in the description search.
format: url
TransactionFilterType:
title: Transaction Filter Type
type: string
description: |
Transaction field used to match the search query to transactions.
Current list of valid values:
- `merchant_name`
- `category_l1`
- `category_l2`
- `description`
- `tag`
TransactionSearchMetadata:
title: Transaction Search Metadata
type: object
required:
- query
- expires_in
properties:
query:
$ref: '#/components/schemas/TransactionSearchQuery'
next_page_token:
$ref: '#/components/schemas/NextPageToken'
results:
$ref: '#/components/schemas/Results'
expires_in:
$ref: '#/components/schemas/TransactionSearchExpirySeconds'
TransactionSearchInsightMetadata:
title: Transaction Search Insight Metadata
type: object
required:
- query
- expires_in
properties:
query:
$ref: '#/components/schemas/TransactionSearchQuery'
expires_in:
$ref: '#/components/schemas/TransactionSearchExpirySeconds'
TransactionSearchQuery:
title: Transaction Search Query
type: object
required:
- from
- to
properties:
user_input:
type: string
merchant_name:
type: string
category_l1:
type: string
category_l2:
type: string
description:
type: string
tag:
type: string
from:
type: string
description: |
The date from when results were retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
This is either populated with the default value used when retrieving the results, or the user specified parameter.
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
to:
type: string
description: |
The date up to when results were retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
This is either populated with the default value used when retrieving the results, or the user specified parameter.
Examples:
- `2023-03-17T17:29:51Z`
- `2023-03-17T17:29:51-08:00`
account_ids:
type: array
items:
type: string
description: |
Account ids used to filter results. Account ids are ORd when supplied as query parameters
credit_debit_indicator:
type: string
enum:
- credit
- debit
amount_min:
type: string
amount_max:
type: string
TransactionsContentType:
title: Transactions Content Type
type: string
enum:
- application/bud-transaction-v3+json
- application/bud-transaction-id+json
default: application/bud-transaction-v3+json
description: |-
Defines the transactions' format for the response.
| MIME type | Description |
|:-----------------------------------:|:-------------------------------------------------------------------------------------------------------------:|
| application/bud-transaction-v3+json | The full transactcion model, including all of Bud's enrichments |
| application/bud-transaction-id+json | Just the IDs of each transaction, useful if your transactions are stored / cached outside of the Bud platform |
TransactionSearchExpirySeconds:
type: integer
format: seconds
description: The number of seconds the search is stored. After this duration elapses, the search will expire and all requestes using it's ID will return `Not Found` errors.
NextPageToken:
type: string
description: |
The token to use to fetch the next page of results. This is only set if there are more results to fetch.
Results:
type: integer
description: The number of results included in this page.
CustomerApplicationID:
title: Customer Application ID
type: string
format: uuid
description: |
The unique identifier for a customer application.
ConnectionID:
title: Connection ID
type: string
format: uuid
description: |
The unique identifier for a customer application's link (for connecting accounts).
DateTimeISO8601:
title: Date/Time (ISO 8601) - YYYY-MM-DDTHH:MM:SSTZ
type: string
description: |
A date (and time) in ISO 8601 format.
example: '2022-05-11T15:30:39Z'
Applicant:
title: Applicant
type: object
description: |
Applicant associated to a financial application.
required:
- first_name
- last_name
properties:
first_name:
type: string
description: First (or "given") name.
last_name:
type: string
description: Last (or "family") name.
CustomerLink:
title: Customer Link
type: object
description: |
Contains a URL that can be provided to a customer in order for them to connect
up their accounts (and have their data associated to the application).
Also contains information about the status of the link's usage (e.g. when it was
issued/created, whether it has been accessed, whether it has expired).
required:
- created_at
- url
- finished_connecting_accounts
- expired
- status
nullable: true
properties:
created_at:
allOf:
- description: Date/time that the customer application link was created.
- $ref: '#/components/schemas/DateTimeISO8601'
url:
type: string
description: |
Full URL for the customer to connect their accounts.
finished_connecting_accounts:
type: boolean
description: |
Indicates if the customer has finished connecting all of their
accounts (i.e. they've reached the end of the flow).
expired:
type: boolean
description: |
Indicates whether the link is no longer usable by the customer
(i.e. the customer has taken too long to complete the flow).
status:
type: string
enum:
- requested
- in_progress
- completed
- expired
description: |
Indicates the status of the connection.
- `requested`: URL has been generated, but customer hasn't started the journey.
- `in_progress`: Customer has followed the URL and is connecting accounts.
- `completed`: Customer successfully connected all their accounts.
- `expired`: Customer failed to connect all their accounts before the URL became inactive.
ReviewStatus:
title: Review Status
type: string
description: |
Indicates whether an application has been reviewed or not.
- Empty string indicates it has not been reviewed
- `reviewed` indicates that it has been reviewed.
Note: this is subject to potentially have more statuses in the future.
enum:
- ''
- reviewed
Metadata:
title: Metadata
type: object
description: |
These fields add additional context to a customer's application.
Their visibility and relevance depends on the configuration of the
dashboard.
properties:
application_id:
type: string
description: |
An optional ID to associate with this customer's application
with (e.g. if the application is related to another system
with a different identifier, use that one here).
customer_id:
type: string
description: |
An optional ID to associate with this customer with (e.g. if
the customer exists on another system with a different
identifier, use that one here).
advisor_name:
type: string
description: |
Name of the advisor in charge of assessing the customer's
application.
account_connection_initiator:
type: string
enum:
- customer
- advisor
description: |
Determines whether the customer's application requires the
advisor to upload financial data, or the customer (via a
generated link).
additionalProperties:
type: string
description: |
Any other additional data you wish to associate to a customer's
application. This will not be visible within the dashboard.
CustomerApplication:
title: Customer Application
type: object
description: Details relating to a customer's application
required:
- accounts_connected
- application_id
- creation_date
- customer_id
- deletion_date
- financial_data_consent
- initiator_id
- metadata
- primary_applicant
- review_status
- secondary_applicants
properties:
application_id:
$ref: '#/components/schemas/CustomerApplicationID'
creation_date:
allOf:
- description: Date that the application was created on.
- $ref: '#/components/schemas/DateTimeISO8601'
deletion_date:
allOf:
- description: Date that the application (and customer data) will be deleted from the platform. May be empty if no date is set.
- $ref: '#/components/schemas/DateTimeISO8601'
customer_id:
type: string
format: uuid
description: Bud Customer ID (used for fetching associated financial data)
initiator_id:
nullable: true
type: string
format: uuid
description: ID of the user who initiated the application (if it was created via the dashboard).
primary_applicant:
allOf:
- description: First and last name of the primary applicant.
- $ref: '#/components/schemas/Applicant'
secondary_applicants:
type: array
description: First and last names of the secondary applicants.
items:
$ref: '#/components/schemas/Applicant'
accounts_connected:
type: integer
description: |
Total number of accounts the customer has connected.
customer_link:
$ref: '#/components/schemas/CustomerLink'
review_status:
$ref: '#/components/schemas/ReviewStatus'
review_date:
$ref: '#/components/schemas/DateTimeISO8601'
metadata:
$ref: '#/components/schemas/Metadata'
financial_data_consent:
$ref: '#/components/schemas/FinancialDataConsentType'
FinancialDataConsentType:
anyOf:
- $ref: '#/components/schemas/OneTimeFinancialDataConsentType'
description: |
Monitoring type for an application refers to the strategy for ingesting data via a customers financial provider.
If no monitoring type is provided, the setting will default to the clients configured type.
OneTimeFinancialDataConsentType:
type: string
enum:
- one_time
description: |
Indicates that data ingestion connections with external providers will be a one-time use only.
After authentication and ingestion, the consent will be automatically revoked.
If additional data is required, a new connection will need to be established.
GetCustomerApplicationsResponse:
title: Get Customer Application Response
type: object
description: Response to the retrieve customer application endpoint
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
$ref: '#/components/schemas/CustomerApplication'
metadata:
type: object
required:
- results
- next_page_token
properties:
results:
type: integer
description: |
Total number of applications returned.
next_page_token:
type: string
description: |
Token to pass to the endpoint (with query parameter `page_token`)
to get the next page of applications in the collection.
This value is empty if this is the last page.
PrimaryApplicant:
title: Primary Applicant
allOf:
- description: First and last name of the primary applicant.
- $ref: '#/components/schemas/Applicant'
SecondaryApplicants:
title: Secondary Applicants
type: array
description: First and last names of the secondary applicants.
items:
$ref: '#/components/schemas/Applicant'
PostCustomerApplicationsRequest:
title: Post Customer Application Request
type: object
description: Details required in order to create a new customer application
required:
- primary_applicant
properties:
primary_applicant:
$ref: '#/components/schemas/PrimaryApplicant'
secondary_applicants:
$ref: '#/components/schemas/SecondaryApplicants'
financial_data_consent:
$ref: '#/components/schemas/FinancialDataConsentType'
metadata:
$ref: '#/components/schemas/Metadata'
PostCustomerApplicationsResponse:
title: Post Customer Applications Response Object
type: object
description: Details provided back to the client when a new customer application has been created
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
required:
- application_id
- customer_id
- expires_at
properties:
application_id:
$ref: '#/components/schemas/CustomerApplicationID'
customer_id:
$ref: '#/components/schemas/CustomerID'
expires_at:
$ref: '#/components/schemas/DateTimeISO8601'
GetCustomerApplicationResponse:
title: Get Customer Applications Response
type: object
description: Details provided back to the client when requesting information relating to a customer's application
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/CustomerApplication'
metadata:
required:
- timezone
- date_range_end
- date_ranges
properties:
timezone:
$ref: '#/components/schemas/TimezoneIdentifier'
date_range_end:
$ref: '#/components/schemas/DateRangeEnd'
date_ranges:
type: array
items:
$ref: '#/components/schemas/DateRange'
description: |
Date ranges corresponding to the choice of `date_range_end`, `timezone` and `date_period` parameters
in the URL query.
These from/to dates can be used for querying other financial data endpoints to within
specific periods of time (e.g. 1 month, 5 months, etc...), with timezones accounted for.
DateRangeEnd:
type: string
enum:
- latest_calendar_month
- latest_date
description: |
Determines whether the date range corresponds to a full calendar month or months to the date of the most
recent account connection.
**Example**: if the customer connects their accounts on `13th July`, then under `latest_calendar_month`, the end date
taken will be `30th June`, and the months back from there will be full calendar months (e.g. 1 month would be
`1st June` to `30th June`). Under `latest_date`, the dates would be `14th June` to `13th July`.
DateRange:
required:
- from
- to
- duration
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
duration:
$ref: '#/components/schemas/DayOrMonth'
DayOrMonth:
type: string
pattern: ^P[0-9]+M|D$
description: |
ISO 8601 date period string representing `n` months or days (e.g. 3 months = `P3M`, 4 days = `P4D`).
PostCustomerLinksRequest:
title: Post Customer Links Request Object
type: object
description: Details required when requesting a new link for a given customer's application
properties:
send_to:
type: string
format: email
description: If provided, the customer will receive an email with the generated link embedded.
redirect_url:
type: string
format: url
description: URL where the customer will be redirected to once they complete the connection flow.
PostCustomerLinksResponse:
title: Post Customer Link Response Object
type: object
description: Details provided back to the client when requesting a new link for a customer application.
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
description: Data object relating to the customer's link.
required:
- link
properties:
link:
type: string
format: url
description: URL that the customer should click to trigger the journey.
metadata:
type: object
description: Metadata associated with the customer link
required:
- connection_id
properties:
connection_id:
type: string
format: uuid
description: |
A unique ID associated to customer's connection URL (this ID is
contained within the link in the payload).
CreateBucketRequest:
title: Create Bucket Request
required:
- name
- categorisation_model
- buckets
properties:
name:
$ref: '#/components/schemas/Slug'
categorisation_model:
$ref: '#/components/schemas/CategorisationModel'
buckets:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Bucket'
additionalProperties: false
CreateBucketResponse:
title: Create Bucket Response
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- aggregations_v2_buckets_post
data:
required:
- bucket_id
properties:
bucket_id:
type: string
format: uuid
description: |
UUID of newly created bucket.
GetBucketsResponse:
title: Retrieve Buckets Response
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- aggregations_v2_buckets_get
data:
type: array
items:
required:
- bucket_id
- name
- categorisation_model
- created_at
- updated_at
- buckets
properties:
bucket_id:
type: string
format: uuid
name:
type: string
categorisation_model:
$ref: '#/components/schemas/CategorisationModel'
created_at:
$ref: '#/components/schemas/DateTimeISO8601'
updated_at:
$ref: '#/components/schemas/DateTimeISO8601'
buckets:
type: array
items:
type: string
GetBucketResponse:
title: Retrieve Bucket Response
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- aggregations_v2_bucket_get
data:
$ref: '#/components/schemas/BucketDefinition'
metadata:
properties:
category_lookup:
description: |
A nested object mapping used to quickly find the category_l1/l2 pairings of a bucket.
E.g. if you know you have a bucket pairing `BL1`/`BL2`, you can find the `category_l1`/`l2`` it
belongs to by looking it up with `$.metadata.category_lookup[BL1][BL2]`, and it will return
the pairing
```json
{
"category_l1": "...",
"category_l2": "..."
}
```
Use this if you are planning to use category corrections, and want to ensure that your
totals correspond to the correct categories after the correction.
additionalProperties:
additionalProperties:
$ref: '#/components/schemas/CategoryPair'
bucket_lookup:
description: |
A nested object mapping used to quickly find the bucket to which a particular category_l1/l2 pairing
belongs.
E.g. if you know you have a category pair `C1`/`C2`, you can find the `bucket_l1`/`l2`` it
belongs to by looking it up with `$.metadata.bucket_lookup[C1][C2]`, and it will return
the pairing
```json
{
"bucket_l1": "...",
"bucket_l2": "..."
}
```
additionalProperties:
additionalProperties:
$ref: '#/components/schemas/BucketPair'
unbucketed_categories:
description: |
List of categories from the model which do not fit within a category bucket.
Use this to see if your category bucket is possibly missing out on important
categories for your analysis.
type: array
items:
$ref: '#/components/schemas/CategoryPair'
BucketDefinition:
title: Bucket Definition
required:
- bucket_id
- name
- categorisation_model
- buckets
properties:
bucket_id:
type: string
description: |
Permanent ID for the bucket.
name:
$ref: '#/components/schemas/Slug'
categorisation_model:
type: string
description: |
Categorisation model that the categories in this bucket relate to.
See [V2 Categories](https://docs.thisisbud.com/reference/resources_v2_categories_get) for details.
buckets:
type: array
items:
$ref: '#/components/schemas/Bucket'
CategorisationModel:
title: Categorisation Model
type: string
description: |
Categorisation model that the categories in this bucket relate to.
See [V2 Categories](https://docs.thisisbud.com/reference/resources_v2_categories_get) for details.
Bucket:
title: Bucket
required:
- bucket_l1
- criteria
properties:
bucket_l1:
$ref: '#/components/schemas/Slug'
criteria:
type: array
items:
$ref: '#/components/schemas/Criteria'
additional_data:
$ref: '#/components/schemas/AdditionalData'
Criteria:
title: Bucket Criteria
required:
- bucket_l2
- category_l1
- category_l2
properties:
bucket_l2:
$ref: '#/components/schemas/Slug'
category_l1:
$ref: '#/components/schemas/Slug'
category_l2:
$ref: '#/components/schemas/Slug'
additional_data:
$ref: '#/components/schemas/AdditionalData'
Slug:
type: string
pattern: ^[a-zA-Z-_0-9]*$
AdditionalData:
title: Additional Data
description: |
Set your own additional properties for a bucket for your own use-cases, e.g.
```json
{
"additional_data": {
"display_name": "Bucket name",
"some_custom_field": "value_1"
}
}
```
additionalProperties: true
CategoryPair:
title: Category L1/L2 Pair
required:
- category_l1
- category_l2
properties:
category_l1:
$ref: '#/components/schemas/Slug'
category_l2:
$ref: '#/components/schemas/Slug'
BucketPair:
title: Bucket L1/L2 Pair
required:
- bucket_l1
- bucket_l2
properties:
bucket_l1:
$ref: '#/components/schemas/Slug'
bucket_l2:
$ref: '#/components/schemas/Slug'
GroupType:
title: Group
type: string
enum:
- bucket_l1
- bucket_l2
- month
GetBucketTotalsResponse:
title: Retrieve Bucket Totals Response
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- aggregations_v2_bucket_totals_get
data:
type: array
items:
$ref: '#/components/schemas/TotalGroup'
metadata:
required:
- date_from
- date_to
- group_by
- currency
properties:
date_from:
$ref: '#/components/schemas/DateTimeISO8601'
date_to:
$ref: '#/components/schemas/DateTimeISO8601'
group_by:
type: array
items:
$ref: '#/components/schemas/GroupType'
currency:
$ref: '#/components/schemas/BudCurrency'
TotalGroup:
title: Total Group
required:
- group_name
- group_type
- incoming
- outgoing
- transaction_count
- _links
properties:
group_name:
type: string
description: |
Name for the particular grouping, corresponding to the `group_type`.
If `group_type` is:
- `bucket_l1`: the name will be the corresponding `bucket_l1`.
- `bucket_l2`: the name will be the corresponding `bucket_l2`.
- `month`: then the name will be the date range for that full month.
- If the date range in this group is a full month (e.g. 1st to the last day of the month)
then it will be shortened to `YYYY-MM` (e.g. `2024-03`)
- Otherwise it is a conjunction of full ISO timestamps (e.g. `2024-01-05T00:00:00Z|2024-02-04T23:59:59Z`)
group_type:
$ref: '#/components/schemas/GroupType'
incoming:
$ref: '#/components/schemas/GroupStatistic'
outgoing:
$ref: '#/components/schemas/GroupStatistic'
subtotals:
type: array
items:
type: object
description: |
Nested subgroups if the query has multiple `group_by` options.
E.g. if `group_by=bucket_l1,bucket_l2`, then `subtotals` will contain the array of `bucket_l2` subtotals
within this `bucket_l1` grouping.
Schema for this object recursive (and so has properties `group_name`, `group_type`, `subtotals`, etc...)
required:
- group_name
- group_type
- incoming
- outgoing
- transaction_count
- _links
properties:
group_name:
type: string
group_type:
$ref: '#/components/schemas/GroupType'
incoming:
$ref: '#/components/schemas/GroupStatistic'
outgoing:
$ref: '#/components/schemas/GroupStatistic'
subtotals:
type: array
items:
type: object
transaction_count:
type: integer
_links:
$ref: '#/components/schemas/GroupTransactionLinks'
transaction_count:
type: integer
description: |
Total number of transactions within the group.
_links:
$ref: '#/components/schemas/GroupTransactionLinks'
GroupStatistic:
title: Group Statistic
required:
- total
- transaction_count
- _links
properties:
total:
$ref: '#/components/schemas/BudAmount'
monthly_average:
$ref: '#/components/schemas/BudAmount'
transaction_count:
type: integer
_links:
$ref: '#/components/schemas/GroupTransactionLinks'
GroupTransactionLinks:
title: Transaction Links
required:
- transactions
properties:
transactions:
type: string
description: |
An absolute path to the subset of transactions that derived this particular total.
Prepend with the API host to get a fully resolved URL.
The same headers as [Retrieve Transactions V2](https://docs.thisisbud.com/reference/v2_transactions_get) apply.
The response structure matches the [Retrieve Transactions V2](https://docs.thisisbud.com/reference/v2_transactions_get) endpoint.
OperationId:
title: Operation Id Field
type: string
description: A unique identifier/reference associated with a given endpoint/operation
Error:
title: Error Object
type: object
nullable: true
description: Contains a field specific error message
additionalProperties:
type: string
Errors:
title: Array of Error Object
description: Contains a list of error messages
type: object
additionalProperties:
type: array
items:
type: string
ServerErrorResponse:
title: Server Error Response
type: object
required:
- operation_id
- code_id
- message
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
description: A descriptive enough string that is linked to the reason for the error.
message:
type: string
description: An actual user friendly error message.
errors:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/Errors'
MaintenanceWindowObject:
title: Maintenance Window Object
type: object
description: Details on any scheduled maintenance windows
properties:
start:
type: string
description: The start datetime (ISO8601) of the maintenance window
end:
type: string
nullable: true
description: The end datetime (ISO8601) of the maintenance window. When this value is `null` it means Bud will manually remove the maintenance flag when the provider is back healthy.
OBProvider:
title: Open Banking Providers
type: object
required:
- provider
- display_name
- maintenance_window
- maintenance_status
- icon
- regions
- mobile_only
properties:
provider:
type: string
description: The name of the available open banking provider used as an identifier throughout Bud's API services
display_name:
type: string
description: The name of the available open banking provider used for display purposes
maintenance_window:
anyOf:
- $ref: '#/components/schemas/MaintenanceWindowObject'
- type: object
nullable: true
maintenance_status:
type: string
description: The status of the maintenance window associated with the provider
enum:
- active
- inactive
icon:
type: string
description: A URL for the icon of the corresponding provider
regions:
type: array
description: A list of the different regions (i.e. country codes in ISO 3166 format) associated with the open banking provider
items:
type: string
mobile_only:
type: boolean
description: If true, the provider is only available on mobile devices and requires a dedicated provider app to be installed on the device
ResultsMetadata:
title: Results Metadata Object
type: object
description: Metadata associated with the response schema
properties:
results:
type: number
description: The number of results returned
ProviderTypes:
title: Provider Types
type: array
description: One or more provider types that can be used to filter the list of providers that are shown to the customer during the connection flow. If no filter is applied, all types of provider are returned. Note that on Bud's sandbox environment, only sandbox providers will be returned.
items:
type: string
enum:
- business
- retail
- sandbox
AuthGatewayURLRequestv2:
title: Authorisation Gateweay URL Request Payload
type: object
required:
- redirect_url
properties:
redirect_url:
type: string
description: URL where the user will be redirected to once they have completed the TPP Connection flow. This can be a web based URL or a mobile application internal URL.
nullable: false
maxLength: 2083
providers:
type: array
nullable: true
description: |
Specify a list of one or more providers that will be displayed to the customer during the connection flow. If only a single provider is given, the customer will no longer be shown the select provider screen.
Note, that these must match the `provider_id` returned by the Retrieve OB Providers endpoint.
items:
type: string
provider_types:
$ref: '#/components/schemas/ProviderTypes'
connect_more_accounts_button:
type: boolean
nullable: true
description: When enabled, the customer will see an additional button at the end of the connection flow that allows them to start the connection flow again in order to connect to a new provider.
accounts_summary:
type: boolean
nullable: true
description: When enabled, the customer will be shown a summary screen at the endpoint of the flow that lists the names and balances of all of the accounts that the customer has active consents for (including those connected in previous sessions).
initial_screen:
type: string
description: |
The first screen that the customer will be shown. When value is 'accounts_summary' the customer will see a list of the names and balances of the accounts that the customer currently has active consents for.
When value is 'connect_accounts', the customer will see a list of providers to connect their accounts with. By default this value is 'connect_accounts'.
When the value is 'download_data', the customer can download their data in a JSON file.
When the value is 'reconfirm_consent', the customer will be taken through the reconfirmation of consent journey. If the customer only has one consent they will skip the consent selection screen.
When the value is 'revoke_consent', the customer can revoke consent for accounts they have previously connected.
enum:
- accounts_summary
- connect_accounts
- download_data
- reconfirm_consent
- revoke_consent
nullable: true
reconfirm_consent:
deprecated: true
type: boolean
nullable: true
description: This body parameter has been deprecated. Please use the initial_screen option reconfirm_consent. When enabled, the customer will be taken through the reconfirmation of consent journey. If the customer only has one consent they will skip the consent selection screen. Once they select the option to renew their consent, Bud will either extend the consent expiry date by 90 days from today's date or (if required) send the customer to the provider to go through Strong Customer Authentication (SCA) before updating the consent expiry date.
reconfirm_consent_redirect:
type: boolean
nullable: true
description: When enabled, once a customer has reconfirmed consent they will be redirected back to the client redirect_url bypassing the account summary screen. This should be used if you don’t want your customers to see the Bud account summary screen.
enable_async_connect:
type: boolean
nullable: true
description: When enabled, once the consent authorisation has completed, the customer will be moved on in the flow. The data is then fetched and enriched in the background, instead of the customer waiting on a loading spinner
skip_success_screen:
type: boolean
nullable: true
description: When enabled, once the customer has completed the connect flow, they will be redirected back to the client redirect_url bypassing the success screen. This should be used if you don’t want your customers to see the Bud success screen.
customer_email:
type: string
format: email
description: |
When provided, an email will be delivered to the customer with a URL for managing their consents with you.
This allows the customer to separately view, revoke and reconfirm consents for accounts that they have agreed to share with you, as well as download the financial data for their own records.
Use this option if your application does not already provide a means for customers to manage their financial data consents.
**Note**: for some clients, we enforce that customers have access to this consent management feature. In this case, even if `customer_email` is not provided, the customer will be prompted at the start of the Connect flow to provide their email address, so that the URL will still be delivered to them.
AuthGatewayURLResponse:
title: Authorisation Gateweay URL Response
type: object
description: Expected response structure.
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
description: Information related to the unique (customer specific) Authorisation Gateway URL
required:
- url
properties:
url:
type: string
description: An Authorisation Gateway URL, allowing Customers to connect an Open Banking provider via Bud's TPP Connection UI
format: url
BadRequestResponse:
title: Bad Request Response
type: object
description: Expected response structure
required:
- operation_id
- code_id
- message
- errors
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
description: A descriptive enough string that is linked to the reason for the error.
message:
type: string
errors:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/Errors'
TaskType:
type: string
enum:
- connect
- refresh
- revoke
- consent-refresh
description: The type of task that completed
OBSyncWebhookBody:
title: OB Synchronisation Webhook Payload
type: object
description: |
The payload sent to the client defined webhook (via the console) when an Open Banking Synchronisation (connect or refresh) task completes.
required:
- data
properties:
operation_id:
deprecated: true
type: string
enum:
- connect
- refresh
description: Use data.task_type instead
data:
description: Data Segments being loaded
required:
- task_type
- customer_id
- task_id
- status
properties:
task_id:
description: The task identifier that the event relates to
type: string
example: e145c656-4a90-45db-a025-af7765482c8c
status:
description: The completion status of the task
type: string
enum:
- Completed
- Failed
task_type:
$ref: '#/components/schemas/TaskType'
customer_id:
description: The customer the event relates to
type: string
example: 19677d9f-90e7-44a6-a32e-566990623da4
has_new_transactions:
type: string
enum:
- 'true'
- 'false'
description: |
To describe whether new transactions have been pulled from the relevant ASPSP during the refresh. Note that if this field is set to `false` then there is no need to make a request to any other downstream endpoints to collect the data related to that customer.
reconnect_required:
type: string
enum:
- 'true'
- 'false'
description: If true, the customer must re-connect to the specified provider
provider:
type: string
description: Name of the provider (banking institution) the task interacted with
consent_id:
type: string
description: The consent identifier that the event relates to
ConnectResultCodes:
type: string
description: The result of the operation. Either success or various error codes.
enum:
- success
- auth_denied
- auth_expired
- auth_used
- awaiting_authorisation
- connection_expired
- connection_not_found
- connection_permission
- connection_reauthenticate
- connection_revoked
- connection_status
- consent_not_found
- extension_not_permitted
- failed_body_decode
- failed_validation
- internal_auth_error
- internal_error
- internal_timeout
- internal_transient_error
- provider_unauthorised
- provider_unavailable
- provider_endpoint_deprecated
- provider_endpoint_unimplemented
- provider_endpoint_unsupported
- provider_failure
- provider_maintenance
- provider_marked_account_invalid
- provider_not_found
- provider_request_limit
- provider_timeout
- resource_not_found
- task_not_found
OBConnectWebhookBody:
title: OB Webhook Payload
type: object
description: |
The payload sent to the client defined webhook (via the console) when an Open Banking (connect or refresh) task completes.
required:
- data
properties:
data:
description: Open Banking Task Event Data
required:
- task_type
- customer_id
- task_id
- status
- result
properties:
task_id:
description: The task identifier that the event relates to
type: string
example: e145c656-4a90-45db-a025-af7765482c8c
status:
type: string
description: The general status of a task
enum:
- Completed
- Failed
task_type:
type: string
enum:
- connect
- refresh
description: The type of task that completed
customer_id:
description: The customer the event relates to
type: string
example: 19677d9f-90e7-44a6-a32e-566990623da4
result:
$ref: '#/components/schemas/ConnectResultCodes'
provider:
type: string
description: Name of the provider (banking institution) the task interacted with
consent_id:
type: string
description: The consent identifier that the event relates to
OpenBankingAuthoriseRequest:
title: Provider
type: object
description: Expected request payload structure
required:
- provider
properties:
provider:
type: string
description: The identifier of the ASPSP (bank) the Customer is requesting the authorisation URL for. This should be a provider value returned from a call to [Retrieve OB Providers](#tag/Create-OB-Connection-TSP/operation/open_banking_providers_get)
redirect_url:
type: string
description: This is the url that your Customer will be redirected to when using the Bud Connect product. If you wish to use your own license and callback infrastructure this parameter will have no effect and the provider_redirect_url parameter should be used instead.
provider_redirect_url:
type: string
description: This is the url that your Customer will be redirected to once they have authorised with the relevant provider. This should only be used when using your own license and wish to use the Submit Authorisation Codes endpoint. If you wish to use Bud's call back then the redirect_url must be provided.
consent_id:
type: string
description: Uses the previous consent id of your customer to re-authenticate their consent.
TaskId:
title: Task Id
type: string
description: Bud Task identifier returned from an async task for the requested action
TaskCreatedView:
title: Task Created View
description: Standard successful task created response.
type: object
required:
- task_id
- provider
properties:
task_id:
$ref: '#/components/schemas/TaskId'
provider:
type: string
description: The provider (ASPSP) associated with this task
AsyncTaskMetadata:
title: Async Task Metadata
type: object
description: Metadata associated with an asynchronous task
properties:
status:
type: string
description: The status of the job associated with the specified task id
enum:
- Completed
- Pending
- Failed
next_url:
type: string
description: The URL to call to obtain the results of the task
next_url_delay:
type: number
description: The time in milliseconds that the client should wait before polling the relevant GET endpoint with the above task id
TaskCreatedResponseOB:
title: Task Created Response
type: object
description: Expected response structure
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/TaskCreatedView'
metadata:
$ref: '#/components/schemas/AsyncTaskMetadata'
TaskAuthorise:
title: Open Banking Authorise Response
type: object
description: Result of GET authorise taskId
required:
- provider
- status
- task_id
properties:
provider:
type: string
description: Name of the provider (banking institution)
result:
$ref: '#/components/schemas/ConnectResultCodes'
status:
type: string
description: The status of the job associated with the specified task id
enum:
- Completed
- Pending
- Failed
task_id:
$ref: '#/components/schemas/TaskId'
url:
type: string
description: The authentication URL for a given bank
TaskManagerMetaData:
title: Task Status Metadata
type: object
description: Standard metadata response from the OB task manager
required:
- status
- next_url
- next_url_delay
properties:
status:
type: string
description: The status of the job associated with the specified task id
enum:
- Completed
- Pending
- Failed
next_url:
type: string
description: The url to try next if the `status` property returned is `Pending`
next_url_delay:
type: number
description: The time in milliseconds that the client should wait before polling the relevant GET endpoint with the above task id if the `status` property returned is `Pending`
TaskAuthoriseResponse:
title: Open Banking Authorise Request Response
type: object
description: Expected response structure
required:
- operation_id
- metadata
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/TaskAuthorise'
metadata:
$ref: '#/components/schemas/TaskManagerMetaData'
AuthorisationCodesRequest:
title: Authorisation Codes Request Payload
type: object
required:
- state
additionalProperties: true
properties:
state:
type: string
description: The task ID
code:
type: string
description: Code parameter returned in redirect parameters
IngestResponseStatus:
title: Ingest Response Status
description: Ingest response status.
type: string
enum:
- Completed
- Pending
- Failed
AuthorisationCodesResponse:
title: Authorisation Codes Response Payload
type: object
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
description: Details regarding the response object for the authorisation codes response.
properties:
task_id:
$ref: '#/components/schemas/TaskId'
provider:
type: string
description: Name of the provider (banking institution)
status:
$ref: '#/components/schemas/IngestResponseStatus'
result:
type: string
enum:
- success
- auth_denied
- auth_expired
- auth_used
- awaiting_authorisation
- connection_expired
- connection_not_found
- connection_permission
- connection_reauthenticate
- connection_revoked
- connection_status
- consent_not_found
- extension_not_permitted
- failed_body_decode
- failed_validation
- internal_auth_error
- internal_error
- internal_timeout
- internal_transient_error
- provider_unauthorised
- provider_unavailable
- provider_endpoint_deprecated
- provider_endpoint_unimplemented
- provider_endpoint_unsupported
- provider_failure
- provider_maintenance
- provider_marked_account_invalid
- provider_not_found
- provider_request_limit
- provider_timeout
- resource_not_found
- task_not_found
GetOBConnectData:
title: Open Banking Synchronisation Status
type: object
description: Status of an Open Banking Aggregation connect or refresh task
required:
- provider
- step
- text
- task_id
properties:
provider:
type: string
description: The name of the provider the task is trying to connect to
step:
type: integer
description: At what step or stage the connection process is at
enum:
- 1
- 2
- 3
- 4
text:
type: string
description: A description of what stage the connection process is at
enum:
- Fetching access token
- Fetching accounts
- Fetching balances and transactions
- Completed
bank_name:
type: string
deprecated: true
description: The name of the provider the task is trying to connect to. Replaced with `provider`
reconnect_required:
type: boolean
description: If true, the customer must re-connect to the specified provider
result:
$ref: '#/components/schemas/ConnectResultCodes'
status:
title: The Task Status
type: string
description: The general status of a task
enum:
- Pending
- Completed
- Failed
task_id:
$ref: '#/components/schemas/TaskId'
TaskStatusCaps:
title: The Task Status
type: string
description: The general status of a task
enum:
- Pending
- Completed
- Failed
OpenBankingConnectResponse:
title: Open Banking Connect Response
type: object
description: Expected response structure
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/GetOBConnectData'
metadata:
type: object
properties:
status:
$ref: '#/components/schemas/TaskStatusCaps'
next_url:
description: The URL to call to obtain the results of the task
type: string
next_url_delay:
description: Recommended delay in milliseconds before next call
type: number
OpenBankingRefreshRequest:
title: Open Banking Refresh Payload
type: object
description: Expected request payload structure
required:
- provider
properties:
provider:
type: string
description: The name of the provider the task is trying to connect to
from:
type: string
description: |
The datetime (ISO 8601) that defines the time since when the Customer's data needs to be collected.
Defaults to the datetime of the last pull of transactions less seven days to account for any potential changes to the most recent set of transactions.
Refreshes can only go back to a maximum of 90 days from the current date.
to:
type: string
description: |
The datetime (ISO 8601) that defines the time up to which the Customer's data needs to be collected. Defaults to the current datetime.
Refreshes can only go back to a maximum of 90 days from the current date.
OBRefreshWebhookBody:
title: OB Webhook Payload
type: object
description: |
The payload sent to the client defined webhook (via the console) when an Open Banking (connect or refresh) task completes.
required:
- data
properties:
data:
description: Open Banking Task Event Data
required:
- task_type
- customer_id
- task_id
- status
- result
properties:
task_id:
description: The task identifier that the event relates to
type: string
example: e145c656-4a90-45db-a025-af7765482c8c
status:
type: string
description: The general status of a task
enum:
- Completed
- Failed
task_type:
type: string
enum:
- connect
- refresh
description: The type of task that completed
customer_id:
description: The customer the event relates to
type: string
example: 19677d9f-90e7-44a6-a32e-566990623da4
result:
$ref: '#/components/schemas/ConnectResultCodes'
has_new_transactions:
type: string
enum:
- 'true'
- 'false'
description: |
To describe whether new transactions have been pulled from the relevant ASPSP during the refresh. Note that if this field is set to `false` then there is no need to make a request to any other downstream endpoints to collect the data related to that customer.
reconnect_required:
type: string
enum:
- 'true'
- 'false'
description: If true, the customer must re-connect to the specified provider
provider:
type: string
description: Name of the provider (banking institution) the task interacted with
consent_id:
type: string
description: The consent identifier that the event relates to
ReconnectRequired:
type: boolean
description: Indicator as to whether the account needs to be connected again, through SCA authentication.
TaskView:
title: Task View
description: A task view.
type: object
properties:
task_id:
$ref: '#/components/schemas/TaskId'
provider:
type: string
description: The provider (ASPSP) associated with this task
result:
$ref: '#/components/schemas/ConnectResultCodes'
status:
$ref: '#/components/schemas/TaskStatusCaps'
reconnect_required:
$ref: '#/components/schemas/ReconnectRequired'
step:
type: number
description: The step that this task is currently where 4 = Completed.
enum:
- 1
- 2
- 3
- 4
text:
type: string
description: A description of the step this task is currently at. In order from step 1 to step 4.
enum:
- Fetching access token
- Fetching accounts
- Fetching balances and transactions
- Completed
HasNewTransactions:
type: boolean
description: |
To describe whether new transactions have been pulled from the relevant
ASPSP during the refresh. Note that if this field is set to `false` then
there is no need to make a request to any other downstream endpoints to
collect the data related to that customer.
OpenBankingRefreshResponse:
title: Refresh Task Response
type: object
description: Expected response structure
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/TaskView'
metadata:
type: object
description: Refresh Response Metadata
properties:
has_new_transactions:
$ref: '#/components/schemas/HasNewTransactions'
status:
$ref: '#/components/schemas/TaskStatusCaps'
next_url:
description: The URL to call to obtain the results of the task
type: string
next_url_delay:
description: Recommended delay in milliseconds before next call
type: integer
OBResources:
type: string
enum:
- accounts
- balances
- transactions
- parties
- direct-debits
OpenBankingRefreshRequestV2:
title: Open Banking Refresh V2 Payload
type: object
description: Expected request payload structure
properties:
providers:
type: array
description: Optional parameter defining the name of the providers that a refresh should be completed for. If this is not specified a refresh is completed for all providers that a customer has an authorised consent with.
items:
type: string
from:
type: string
description: |
The datetime (ISO 8601) that defines the time since when the Customer's data needs to be collected.
Defaults to the datetime of the last pull of transactions less seven days to account for any potential changes to the most recent set of transactions.
Refreshes can only go back to a maximum of 90 days from the current date.
to:
type: string
description: |
The datetime (ISO 8601) that defines the time up to which the Customer's data needs to be collected. Defaults to the current datetime.
resources:
type: array
description: Optional list of resources that should be refreshed. Default behaviour is to refresh all resources defined on the customers consent
items:
$ref: '#/components/schemas/OBResources'
TaskV2CreatedView:
title: Refresh V2 Task Created View
description: Standard successful task created response.
type: object
required:
- task_id
- sub_tasks
properties:
task_id:
$ref: '#/components/schemas/TaskId'
sub_tasks:
type: array
items:
$ref: '#/components/schemas/TaskCreatedView'
TaskCreatedV2ResponseOB:
title: Refresh V2 Task Created Response
type: object
description: Expected response structure
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/TaskV2CreatedView'
metadata:
$ref: '#/components/schemas/AsyncTaskMetadata'
RefreshSubtaskWebhookTask:
title: Details of an individual refresh Task
type: object
description: The payload detailing an individual refresh for a single provider
required:
- has_new_transactions
- provider
- reconnect_required
- result
- status
- task_id
properties:
account_ids:
description: An array listing all account ids that were updated as part of this task
type: array
items:
type: string
consent_ids:
description: An array listing all consents that were updated as part of this task
type: array
items:
type: string
has_new_transactions:
$ref: '#/components/schemas/HasNewTransactions'
provider:
type: string
description: Name of the provider (banking institution)
reconnect_required:
$ref: '#/components/schemas/ReconnectRequired'
result:
$ref: '#/components/schemas/ConnectResultCodes'
status:
type: string
description: The general status of a task
enum:
- Completed
- Failed
task_id:
description: The task identifier that the event relates to
type: string
example: e145c656-4a90-45db-a025-af7765482c8c
start_time:
type: string
description: Start timestamp for the task this event relates to
refresh_window:
type: object
description: The boundaries of the refresh task as requested from the provider. If transactions were returned from the provider
properties:
from:
type: string
description: The from timestamp requested with the provider
to:
type: string
description: The to timestamp requested with the provider
consent_details:
type: object
description: Details of the consent used as part of this refresh task
properties:
id:
type: string
description: The id of the consent that was updated as part of this task
expiration_date:
type: string
description: The expiration date of the consent
OBV2WebhookBody:
title: OB V2 Webhook Payload
type: object
description: |
The payload sent to the client defined webhook (via the console) when an Open Banking refresh V2 task completes.
required:
- customer_id
- event
- has_new_transactions
- task_id
- result
- status
properties:
customer_id:
description: The customer the event relates to
type: string
example: 19677d9f-90e7-44a6-a32e-566990623da4
event:
type: string
description: The task type for the event.
has_new_transactions:
$ref: '#/components/schemas/HasNewTransactions'
task_id:
description: The task identifier that the event relates to
type: string
example: e145c656-4a90-45db-a025-af7765482c8c
result:
$ref: '#/components/schemas/ConnectResultCodes'
status:
type: string
description: The general status of a task
enum:
- Completed
- Failed
start_time:
type: string
description: Start timestamp for the task this event relates to
refresh_window:
type: object
description: The boundaries of the refresh task as requested from the provider. If transactions were returned from the provider
properties:
from:
type: string
description: The from timestamp requested with the provider
to:
type: string
description: The to timestamp requested with the provider
sub_tasks:
description: An array of details about each individual refresh subtask
type: array
items:
$ref: '#/components/schemas/RefreshSubtaskWebhookTask'
ProviderOBV2WebhookBody:
title: OB V2 Webhook Payload
type: object
description: |
The payload sent to the client defined webhook (via the console) when an Open Banking refresh V2 task completes.
required:
- event
- task_id
- status
- result
- reconnect_required
- provider
- has_new_transactions
- customer_id
properties:
account_ids:
description: An array listing all account ids that were updated as part of this task
type: array
items:
type: string
consent_ids:
description: An array listing all consents that were updated as part of this task
type: array
items:
type: string
customer_id:
description: The customer the event relates to
type: string
example: 19677d9f-90e7-44a6-a32e-566990623da4
has_new_transactions:
$ref: '#/components/schemas/HasNewTransactions'
provider:
type: string
description: Name of the provider (banking institution)
reconnect_required:
$ref: '#/components/schemas/ReconnectRequired'
result:
$ref: '#/components/schemas/ConnectResultCodes'
status:
type: string
description: The general status of a task
enum:
- Completed
- Failed
task_id:
description: The task identifier that the event relates to
type: string
example: e145c656-4a90-45db-a025-af7765482c8c
event:
type: string
description: The task type for the event.
start_time:
type: string
description: Start timestamp for the task this event relates to
refresh_window:
type: object
description: The boundaries of the refresh task as requested from the provider. If transactions were returned from the provider
properties:
from:
type: string
description: The from timestamp requested with the provider
to:
type: string
description: The to timestamp requested with the provider
consent_details:
type: object
description: Details of the consent used as part of this refresh task
properties:
id:
type: string
description: The id of the consent that was updated as part of this task
expiration_date:
type: string
description: The expiration date of the consent
SubTaskV2View:
title: SubTask V2 View
description: A task view.
type: object
properties:
task_id:
$ref: '#/components/schemas/TaskId'
provider:
type: string
description: The provider (ASPSP) associated with this task
result:
$ref: '#/components/schemas/ConnectResultCodes'
status:
$ref: '#/components/schemas/TaskStatusCaps'
reconnect_required:
$ref: '#/components/schemas/ReconnectRequired'
has_new_transactions:
$ref: '#/components/schemas/HasNewTransactions'
TaskV2View:
title: Task V2 View
description: A task view.
type: object
properties:
task_id:
$ref: '#/components/schemas/TaskId'
result:
$ref: '#/components/schemas/ConnectResultCodes'
status:
$ref: '#/components/schemas/TaskStatusCaps'
has_new_transactions:
$ref: '#/components/schemas/HasNewTransactions'
sub_tasks:
type: array
items:
$ref: '#/components/schemas/SubTaskV2View'
OpenBankingRefreshV2Response:
title: Refresh V2 Task Response
type: object
description: Expected response structure
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/TaskV2View'
metadata:
type: object
description: Refresh Response Metadata
properties:
status:
$ref: '#/components/schemas/TaskStatusCaps'
next_url:
description: The URL to call to obtain the results of the task
type: string
next_url_delay:
description: Recommended delay in milliseconds before next call
type: integer
RawOBConsents:
title: Raw OB Consent
type: object
nullable: true
description: The raw consent as returned by the provider
properties:
ConsentId:
type: string
description: Open Banking consent unique identifier
CreationDateTime:
type: string
format: ISO8601
description: Date and time at which the resource was created.
Permissions:
type: array
description: Specifies the Open Banking account access data types that tied to the consent
items:
type: string
enum:
- ReadAccountsBasic
- ReadAccountsDetail
- ReadBalances
- ReadDirectDebits
- ReadParty
- ReadPartyPSU
- ReadTransactionsBasic
- ReadTransactionsCredits
- ReadTransactionsDebits
- ReadTransactionsDetail
Status:
type: string
description: Specifies the status of consent resource.
enum:
- Authorised
- AwaitingAuthorisation
- Rejected
- Revoked
StatusUpdateDateTime:
type: string
nullable: true
format: ISO8601
description: Date and time at which the resource status was updated.
TransactionFromDateTime:
type: string
nullable: true
format: ISO8601
description: Specified start date and time for the transaction query period.
GetOBConsentsResponseDataItem:
title: Open Banking Consent
type: object
description: Schema to define a given Open Banking consent
required:
- id
- customer_id
- provider
- transaction_from_date
- expiration_date
- created_at
- last_consented_on
- status
- resources
- permissions
- raw_version
- raw_format
properties:
id:
type: string
description: Open Banking consent unique identifier
customer_id:
type: string
description: Bud customer unique identifier, owner of the consent
provider:
type: string
description: Open Banking provider who the consent refers to
transaction_from_date:
type: string
description: Date and time from when the transactions can be retrieved. ISODateTime.
expiration_date:
type: string
description: Date and time when the consent will expired. ISODateTime.
created_at:
type: string
description: Date and time when the consent was created. ISODateTime.
last_consented_on:
type: string
description: Date and time when the consent was last consented on. ISODateTime.
revoked_at:
type: string
description: |
Date and time when the consent was revoked. ISODateTime. This attribute in included in the response only if the status of the consent is `revoked`.
When the consent is invalidated as part of a Bud refresh task, this date time represents the time when the consent was set to `revoked` by Bud during the refresh.
revoke_reason:
type: string
description: |
The reason that the consent was marked as revoked. This attribute in included in the response only if the status of the consent is `revoked`.
enum:
- provider_revoked
- bud_revoked
- single_use
- duplicate_accounts
- access_token_error
- consent_invalid
status:
type: string
description: To describe the status of the consent. Note that the query parameter `status=all` must be provided to be shown consents that have a status of anything but `authorised`
enum:
- awaiting_authorisation
- authorised
- rejected
- revoked
resources:
type: array
description: List of resources this consent has access too
items:
$ref: '#/components/schemas/OBResources'
permissions:
type: array
description: Specifies the Open Banking account access data types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP.
items:
type: string
enum:
- ReadAccounts
- ReadBalances
- ReadDirectDebits
- ReadParties
- ReadTransactions
raw_version:
type: string
description: Version of the raw format of the consent
raw_format:
type: string
description: The format of the consent returned in the raw attribute
enum:
- obie
- amex
- starling
raw:
$ref: '#/components/schemas/RawOBConsents'
account_ids:
type: array
description: A list of the different account identifiers that are associated with this particular consent object.
items:
type: string
last_synced_at:
type: string
description: The date at which the last data refresh (sync) occured for this consent object. For revoked consents this will be the time that the conesnt was revoked.
GetOBConsentsResponse:
title: Available Open Banking Consents
type: object
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
description: List of available consents
items:
$ref: '#/components/schemas/GetOBConsentsResponseDataItem'
metadata:
$ref: '#/components/schemas/ResultsMetadata'
RevokeAccountAccessIntentRequest:
title: Revoke Account Access Intent Payload
type: object
required:
- provider
properties:
provider:
type: string
description: The name of the provider (ASPSP) the Customer is requesting to have their consent revoked for
TaskCreatedMetadata:
type: object
description: Created task metadata response
required:
- status
- next_url
- next_url_delay
properties:
status:
type: string
description: The status of the job associated with the specified task id
enum:
- Pending
next_url:
type: string
description: The url to get the status of the task
next_url_delay:
type: number
description: The time in milliseconds that the client should wait before polling the relevant GET status endpoint
RevokeTaskCreatedResponse:
title: Revoke Task Created Response
type: object
description: Expected response structure
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/TaskCreatedView'
metadata:
$ref: '#/components/schemas/TaskCreatedMetadata'
OBConsentWebhookBody:
title: OB Consent Webhook Payload
type: object
description: |
The payload sent to the client defined webhook (via the console) when an event occurs to a Open Banking Consent.
required:
- data
properties:
data:
description: Consent Event Data
required:
- event
- consent_id
- customer_id
- provider
- updated_at
properties:
event:
description: The event this webhook relates too
type: string
enum:
- open_banking.consent.reconfirmed
- open_banking.consent.reauthorised
- open_banking.consent.revoked
example: open_banking.consent.reconfirmed
consent_id:
type: string
description: The consent this event relates too
example: ab32780a-3d60-4d4d-984f-11ea3ef329cd
customer_id:
description: The customer the consent is associated with
type: string
example: 19677d9f-90e7-44a6-a32e-566990623da4
provider:
description: The provider the consent is associated with
type: string
example: Monzo
updated_at:
description: The date time that the event occurred
type: string
format: date-time
example: '2023-10-02T14:05:55Z'
reason:
type: string
description: |
For the open_banking.consent.revoked event. The reason that the consent was marked as revoked.
enum:
- provider_revoked
- bud_revoked
- single_use
- duplicate_accounts
- access_token_error
- consent_invalid
RevokeAccountAccessIntentTastStatusResponse:
title: Revoke Account Access Intent Response
type: object
description: Expected response from a get status request for a revoke account access intent call
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
title: Revoke Task Data
required:
- task_id
- provider
- status
properties:
task_id:
$ref: '#/components/schemas/TaskId'
provider:
type: string
description: The provider (ASPSP) associated with this task
status:
type: string
description: The status of the job associated with the specified task id
enum:
- Completed
- Pending
- Failed
result:
type: string
description: The result of the operation.
metadata:
type: object
title: Revoke Task Metadata
required:
- status
properties:
status:
type: string
description: The status of the job associated with the specified task id
enum:
- Completed
- Pending
- Failed
next_url:
type: string
description: The url to try next if the `status` property returned is `Pending`
next_url_delay:
type: number
description: The time in milliseconds that the client should wait before polling again, if the `status` property returned is `Pending`
RevokeAccountAccessIntentTaskStatusValidationError:
title: Revoke Account Access Intent Status Validation Error
type: object
required:
- operation_id
- code_id
- message
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
enum:
- failed_validation
message:
type: string
enum:
- invalid request
errors:
type: object
description: Extra information on the validation errors
ConsentReconfirmation:
title: Consent Reconfirmation Outcome
type: object
description: Result of performing a reconfirmation of consent task
required:
- provider_id
- reconnect_required
properties:
provider_id:
type: string
description: The provider that the reconfirmation of consent was performed against
reconnect_required:
$ref: '#/components/schemas/ReconnectRequired'
ReconfirmConsentResponse:
title: Reconfirm Consent Response
type: object
description: Expected response payload structure
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/ConsentReconfirmation'
CustomerID:
type: string
format: uuid
description: A unique identifier for a Customer, as registered on Bud's platform.
example: c3339af9-2426-44d4-9c4d-ddb8fd281e23
CustomerSecret:
type: string
description: The Bud Customer secret used to encrypt customer data. This is required only if the customer secret is not already stored with Bud.
IngestFirstPartyDataWithCustomerID:
title: With Customer ID
properties:
customer_id:
$ref: '#/components/schemas/CustomerID'
customer_secret:
$ref: '#/components/schemas/CustomerSecret'
required:
- customer_id
IngestFirstPartyDataWithCustomerIdempotentIdentifier:
title: With Customer Idempotent Identifier
properties:
customer_idempotent_identifier:
type: string
description: |
An internal client identifier. If specified, a Bud customer will either be automatically created, or utilised to ingest the given data.
This identifier can then be used in place of `X-Customer-Id` across Bud's endpoints.
required:
- customer_idempotent_identifier
IngestAccountDetails:
title: Ingest Account Details
type: object
description: Schema to define any further details about a given account
required:
- scheme_name
- identification
properties:
scheme_name:
type: string
description: Name of the scheme associated with the account
identification:
type: string
description: A unique identifier for the account
secondary_identification:
type: string
description: Any secondary identifier associated with the account
name:
type: string
description: The name of the account holder
IngestAccountIdentifiers:
title: Ingest Account Identifiers
type: object
description: Schema to define identifiers for a given account
required:
- type
- value
properties:
type:
type: string
description: The type of identifier detailed within the value field associated with the account
enum:
- uk_sort_code
- uk_account_number
- iban
- us_account_number
- pan
value:
type: string
description: The identifier associated with the account
BudCurrency:
title: Currency
description: |
The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) of the monetary amount.
Example: `GBP`
type: string
BudMonetaryValue:
title: Monetary Value
description: |
The value of the monetary amount. The value is formatted with the number of decimal places for the respective currency.
Example: `10.98`
type: string
BudAmount:
title: Standard Bud Amount
type: object
description: The monetary amount.
required:
- value
- currency
properties:
value:
$ref: '#/components/schemas/BudMonetaryValue'
currency:
$ref: '#/components/schemas/BudCurrency'
InpAmount:
title: Amount
description: Amount structure
allOf:
- type: object
properties:
local_currency:
allOf:
- description: |
The original three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) the payment was transacted in.
Example: `USD`
- $ref: '#/components/schemas/BudCurrency'
local_value:
allOf:
- description: |
The original value of the payment in the local currency. The value is formatted with the number of decimal places for the respective currency.
Example: `10.98`
- $ref: '#/components/schemas/BudMonetaryValue'
- $ref: '#/components/schemas/BudAmount'
IngestCreditLine:
title: Ingest Credit Line
type: object
description: A set of elements used to provide details on the credit line
required:
- amount
- type
properties:
included:
type: boolean
description: Indicates whether or not the credit line is included in the balance of the account, if not present, credit line is not included in the balance amount of the account
amount:
$ref: '#/components/schemas/InpAmount'
type:
type: string
description: Limit type, in a coded form
enum:
- Available
- Credit
- Emergency
- Pre-Agreed
- Temporary
IngestAccountBalance:
title: Ingest Account Balance
type: object
description: Information surrounding a Customer's Account Balance
required:
- amount
- date_time
- type
- credit_debit_indicator
properties:
amount:
$ref: '#/components/schemas/InpAmount'
credit_debit_indicator:
type: string
description: To describe whether the account balance is in debit or credit
enum:
- incoming_credit
- outgoing_debit
credit_line:
items:
$ref: '#/components/schemas/IngestCreditLine'
date:
type: string
format: YYYY-MM-DD
deprecated: true
description: The date associated with the balance of the given account
time:
type: string
format: hh:mm:ss
deprecated: true
description: The time associated with the balance of the given account
date_time:
type: string
format: date-time
description: RFC 3339 format string of the date time of the balance
type:
type: string
description: |
Describes the state of the balance
| Value | Description |
|:--------------------------|:----------------------------------------------------------|
| `ClosingAvailable` | Closing balance of amount of money that is at the disposal of the account owner on the date specified. |
| `ClosingBooked` | Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. |
| `ClosingCleared` | Closing balance of amount of money that is cleared on the date specified. |
| `Expected` | Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. |
| `ForwardAvailable` | Forward available balance of money that is at the disposal of the account owner on the date specified. |
| `Information` | Balance for informational purposes. |
| `InterimAvailable` | Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. |
| `InterimBooked` | Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. |
| `InterimCleared` | Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. |
| `OpeningAvailable` | Opening balance of amount of money that is at the disposal of the account owner on the date specified. |
| `OpeningBooked` | Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. |
| `OpeningCleared` | Opening balance of amount of money that is cleared on the date specified. |
| `PreviouslyClosedBooked` | Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. |
enum:
- ClosingAvailable
- ClosingBooked
- ClosingCleared
- Expected
- ForwardAvailable
- Information
- InterimAvailable
- InterimBooked
- InterimCleared
- OpeningAvailable
- OpeningBooked
- OpeningCleared
- PreviouslyClosedBooked
IngestCustomerAccount:
title: Ingest Customer Account
description: An account item.
type: object
required:
- provider
- account_id
- currency
- account_type
- account_sub_type
- balances
properties:
provider:
type: string
description: The name of the provider.
account_id:
type: string
description: The unique id associated with the account
currency:
type: string
description: Main currency (in ISO4217 format) of the account
account_type:
type: string
description: The type of the account
enum:
- Business
- Personal
account_sub_type:
type: string
description: The sub type of the account
enum:
- AutoLoan
- BoatLoan
- Brokerage
- BusinessLoan
- CertificateOfDeposit
- ChargeCard
- CheckingAccount
- CreditCard
- CurrentAccount
- DisabilityInsurance
- EMoney
- HealthInsurance
- HomeEquityLoan
- Investment
- Ira
- LiabilityInsurance
- LifeInsurance
- LineOfCredit
- Loan
- MoneyMarket
- Mortgage
- Other
- PersonalLoan
- PrePaidCard
- PropertyInsurance
- Roth
- RvLoan
- Savings
- StudentLoan
- TravelInsurance
- VehicleInsurance
holder_name:
type: string
description: The name of the account holder
details:
deprecated: true
type: array
description: Provides the details to identify an account
items:
$ref: '#/components/schemas/IngestAccountDetails'
account_identifiers:
type: array
description: Provides the details to identify an account
items:
$ref: '#/components/schemas/IngestAccountIdentifiers'
balances:
type: array
description: The balances associated with the account
items:
$ref: '#/components/schemas/IngestAccountBalance'
opening_date_time:
type: string
format: date-time
description: The opening date time of the account in RFC3339 format.
example: '2022-11-12T15:30:00Z'
holders:
type: array
description: The account holders details associated with the account
items:
title: Account_Holder
type: object
properties:
name:
type: string
description: |
The name of the given account holder.
Example: `John Smith`
relationship:
type: string
description: |
The relationship that the individual holder has with the account.
Currently supported values include (but are not necessarily limited to):
- `sole`
- `joint`
- `delegate`
- `unknown`
IngestCustomerWithAccounts:
title: Ingest Customer With Accounts
description: A customer with a accounts data.
type: object
required:
- accounts
oneOf:
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerID'
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerIdempotentIdentifier'
properties:
accounts:
type: array
description: List of accounts that belongs to the customer.
minItems: 1
items:
$ref: '#/components/schemas/IngestCustomerAccount'
IngestAccountsRequest:
title: Bud Accounts Request
description: Ingest accounts expected request body.
type: array
items:
$ref: '#/components/schemas/IngestCustomerWithAccounts'
IngestV2Response:
type: object
required:
- operation_id
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
example: v2_ingest_transactions_post
IngestV2Metadata:
title: Created Task Details
description: Metadata on the created task, including the task_id
type: object
required:
- task_id
properties:
task_id:
type: string
format: uuid
description: Can be used with the transaction status endpoint to retrieve the status of the full enriched process
next_url:
type: string
description: The path to call to obtain the current status of the task.
example: /v2/ingest/status/4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url_delay:
type: number
description: The time in milliseconds that the client should wait before trying to retrieve the current status of the task.
example: 500
IngestV2AsyncResponse:
title: Ingest Transactions V2 Async Response
type: object
allOf:
- $ref: '#/components/schemas/IngestV2Response'
- type: object
required:
- operation_id
- metadata
properties:
metadata:
$ref: '#/components/schemas/IngestV2Metadata'
BodyDecodeError:
type: object
title: JSON Decoding Error
required:
- operation_id
- code_id
- message
- errors
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
enum:
- failed_body_decode
message:
type: string
description: 'High level description on what has failed '
errors:
type: object
description: Contains more details on the decoding error
required:
- decode_error
properties:
decode_error:
type: string
FirstPartyIngestionGenericError:
type: object
title: Content Type Error
required:
- operation_id
- code_id
- message
- errors
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
enum:
- failed_validation
message:
type: string
description: 'High level description on what has failed '
errors:
type: object
description: Error details
properties:
content_type:
type: string
description: The content type header provided in the request is unknown
.customer_id:
type: string
description: Missing customer ID. Index prefix is the index of the customer in the request
.customer_secret:
type: string
description: Missing customer secret. Index is the index of the customer in the request
.accounts:
type: string
description: Missing customer accounts. Index is the index of the customer in the request
example:
operation_id: ingest_accounts_post
code_id: failed_validation
message: validation failure(s) in request payload
errors:
0.customer_secret: The customer secret is mandatory
ValidationMissing:
type: array
title: Missing Fields
description: list of required missing fields for a transaction
items:
type: string
ValidationInvalid:
type: array
title: Invalid Fields
description: list of invalid fields for a transaction
items:
type: string
AccountsDataValidationError:
type: object
title: Accounts validation error
required:
- operation_id
- code_id
- message
- errors
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
enum:
- failed_validation
message:
type: string
description: High level description on what has failed
errors:
type: object
title: Map of customers
description: a map of customer IDs to account validation errors
properties:
missing_fields:
type: object
title: Map of Account
description: |
A map of accounts to missing fields array.
The key contains the index of the account causing issues.
See example
additionalProperties:
$ref: '#/components/schemas/ValidationMissing'
invalid_fields:
type: object
title: Map of Account
description: |
A map of accounts to invalid fields array.
The key contains the index of the account causing issues.
See example
additionalProperties:
$ref: '#/components/schemas/ValidationInvalid'
example:
operation_id: v2_ingest_accounts_post
code_id: failed_validation
message: validation failure(s) in request payload
errors:
1db8c4b5-e5ae-429e-947b-6a4616ffc717:
missing_fields:
accounts[0]:
- provider
- account_id
accounts[1]:
- account_id
invalid_fields:
accounts[0]:
- currency
FPIIngestSucceededWebhookBody:
title: FPI Ingestion Succeeded Webhook Payload
type: object
description: |
The payload sent to the client defined webhook (via the console) when an First Party Ingestion task succeeds.
required:
- data
properties:
data:
type: object
required:
- event
- task_id
- operation_id
properties:
event:
description: The event type
type: string
example: first_party_ingester.ingest.succeeded
task_id:
description: The associated task ID
type: string
example: 3928aca4-b73c-4f13-a540-1b3759e06d27
operation_id:
description: The endpoint ID the operation was related to
type: string
example: v2_ingest_transactions_post
subtask_details:
description: Details of the individual subtasks (customers) of the ingestion
type: array
items:
type: object
required:
- customer_id
properties:
customer_id:
type: string
description: A unique identifier for a Customer, as registered on Bud's platform.
customer_idempotent_identifier:
type: string
description: The `idempotent_identifier` provided when the customer given was created.
FPIIngestFailedWebhookBody:
title: FPI Ingestion Failed Webhook Payload
type: object
description: |
The payload sent to the client defined webhook (via the console) when an First Party Ingestion task fails.
required:
- data
properties:
data:
type: object
required:
- event
- task_id
- operation_id
- result
properties:
event:
description: The event type
type: string
example: first_party_ingester.ingest.failed
task_id:
description: The associated task ID
type: string
example: 3928aca4-b73c-4f13-a540-1b3759e06d27
operation_id:
description: The endpoint ID the operation was related to
type: string
example: v2_ingest_transactions_post
result:
description: The error outcome of the ingestion if it failed
type: string
example: data_mapping_error
subtask_details:
description: Details of the individual subtasks (customers) of the ingestion
type: array
items:
type: object
required:
- customer_id
properties:
customer_id:
type: string
description: A unique identifier for a Customer, as registered on Bud's platform.
customer_idempotent_identifier:
type: string
description: The `idempotent_identifier` provided when the customer given was created.
CloseAccountsRequest:
title: Close Accounts Request
type: array
items:
type: object
oneOf:
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerID'
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerIdempotentIdentifier'
properties:
account_ids:
type: array
items:
type: string
metadata:
type: object
properties:
as_of:
type: string
example: '2025-09-24T14:55:09Z'
description: The datetime that the accounts closed in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339). If not provided, the current datetime will be used.
BadRequestErrorWihoutErrRequired:
type: object
title: JSON Decoding Error
required:
- operation_id
- code_id
- message
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
message:
type: string
description: High level description of what has failed
errors:
type: object
description: Contains more details on the decoding error
ReopenAccountsRequest:
title: Reopen Accounts Request
type: array
items:
type: object
oneOf:
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerID'
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerIdempotentIdentifier'
properties:
account_ids:
type: array
items:
type: string
SynchronousEnrichmentsList:
type: array
description: |
The list of enrichments product to execute during the synchronous execution of the request. Based on this list, the transactions sent will be processed through a number of enrichment flows, and this drives the amount of additional information attached to each transactions in the synchronous process.
The list of available enrichement products during the synchronous ingestion is the following:
- categories
- merchants
The default behaviour is to execute `categories` and `merchants`.
Note: This attribute doesn't limit the execution of all Bud's enrichments, we'll still return a number of additional information (eg: tokens), but it switches on and off the two enrichments listed above.
example:
- categories
- merchants
items:
type: string
enum:
- categories
- merchants
BudTransactionType:
title: transaction_type
type: object
description: |
The code and a description of the transaction type. Providing these fields may help improve enrichment accuracy.
properties:
bud_code:
type: string
description: |
The code representing the type of the given transaction. This typically comes in the form of a proprietary code respective to the __provider__.
Current list of valid accepted codes:
| Code | Meaning
|:------|:-------------------------------------------------------------------|
| DEB | [Debit / Credit] Card |
| CSQ | Cash / Cheque(s) |
| CHG | Charge |
| COR | Correction |
| CPT | Cashpoint / ATM |
| INT | Interest |
| OTH | Other |
| BAT | Bank Transfer (e.g. FP/MP/IB/BACS/CHAPS/SWIFT) |
| DD | Direct Debit |
| SO | Standing Order |
description:
type: string
description: |
A human-readable description of the given __bud_code__.
example: `Contactless POS`
BudClientAttributes:
title: Client Attributes
type: object
description: |
An optional map of key-value string pairs that allows clients to attach arbitrary metadata to the transaction.
This field can be used to store any relevant information specific to the client's needs.
It accepts a maximum of 16 key-value pairs. With a maximum key length of 64 characters and a maximum value length of 256 characters.
properties:
key:
type: string
description: An arbitrary key-value pair for the client attribute.
example:
fraud_score: '0.8'
overdraft_used: 'true'
CustomerTransactionV3:
title: Customer Transaction V3
description: A schema for Bud V3 transaction format
type: object
required:
- transaction_id
- account_id
- description
- date_time
- amount
properties:
transaction_id:
type: string
description: |
Unique, immutable transaction identifier. This can be of any format (not necessarily UUID), with a maximum of 255 characters.
It's important this ID is immutable over time and unique as we use this ID as a key to store the transaction against your customer, so if more than one transaction has the same ID for the same customer, we will store only one of them.
example: 4cef424c-1d7f-4cab-8be2-aee7e1774a00
description:
type: string
description: Free text string providing details on the transaction itself
account_id:
type: string
description: The account identifier that the transaction belongs to. This can be of any format (not necessarily UUID), with a maximum of 255 characters.
example: 2f5b2055-6253-4cd0-b646-06788342a609
date_time:
type: string
format: date-time
description: The date detailing when the transaction occurred, compliant with RFC3339
example: '2022-11-10T23:00:00Z'
value_date_time:
type: string
format: date-time
description: The date detailing when the assets assets involved in the transaction transferred compliant with RFC3339. For credits this is the date that the asset becomes available, for debits this is the date that the asset ceased to be available
example: '2022-11-10T23:00:00Z'
status:
type: string
enum:
- pending
- booked
- declined
default: booked
description: The status of the transaction. If not provided, the default value is `booked`.
example: booked
amount:
type: string
description: |
The value of the monetary amount. The value is formatted with the number of decimal places for the respective currency.
A positive amount is a credit entry and a negative a debit entry.
Example: `"10.98"` or `"-10.98"`
currency:
$ref: '#/components/schemas/BudCurrency'
merchant_category_code:
type: string
description: |
A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245.
An MCC is used to classify a business by the types of goods or services it provides.
merchant_name:
type: string
description: Merchant name
provider:
type: string
description: |
The name of the financial institution the transaction has come from
example: `HSBC`, `NatWest`
Note: if this field is supplied, the value will be normalised to lowercase and `-`, and ` ` characters will be replaced with `_`.
country_code:
type: string
description: |
The country where the transaction occurred, specified using either:
- A 2-letter ISO 3166-1 alpha-2 code (e.g., "US", "GB")
- A 3-letter ISO 3166-1 alpha-3 code (e.g., "USA", "GBR")
- A UN M.49 numeric code (e.g., "840" for United States)
This field enhances merchant identification accuracy and enables automatic travel detection.
When the country_code differs from the `region` in the customer-context, the transaction is assigned appropriate l1 and l2 travel categories.
The value is also used to populate the `country` field in location enrichment data. However, it is converted to a 2-letter ISO 3166-1 alpha-2 code when displayed.
transaction_type:
$ref: '#/components/schemas/BudTransactionType'
running_balance:
type: string
description: |
The balance of the account associated with the transaction after this transaction is made. The value is formatted with the number of decimal places for the respective currency.
A positive amount is a credit balance and a negative a debit balance.
Example: `"10.98"` or `"-10.98"`
client_attributes:
$ref: '#/components/schemas/BudClientAttributes'
suggested_description:
type: string
description: String providing details on the transaction itself as a customer would expect to see the transaction in other locations.
counterparty:
type: object
description: An object containing details of the counterparty in this transaction
properties:
name:
type: string
description: The name of the counterparty involved in this transaction.
identifier:
type: string
description: An identifier for the account of the other party
TransactionWindow:
type: object
title: Transaction Window
description: |
The transaction window is used to describe the entire period for which you have provided full coverage for the transactions within the request.
It is used by Bud to ascertain periods of inactivity on the account(s) in question to ensure accurate data can be provided across downstream endpoints (e.g. Retrieve Balances Over Time).
required:
- account_id
- start
- end
properties:
account_id:
type: string
description: The account identifier that the transaction belongs to
example: 2f5b2055-6253-4cd0-b646-06788342a609
start:
type: string
format: date-time
description: The date detailing the start of the transaction window, compliant with RFC3339
example: '2022-05-10T23:00:00Z'
end:
type: string
format: date-time
description: The date detailing the end of the transaction window, compliant with RFC3339
example: '2022-10-10T23:00:00Z'
TransactionWindowArray:
type: array
description: |
If not provided, the transaction window is inferred from the date of the first and last transactions.
Only a single window per customer account is supported.
items:
$ref: '#/components/schemas/TransactionWindow'
IngestTransactionsV3Request:
title: Bud V3 Transactions Request
description: Ingest transaction expected request body.
type: array
items:
type: object
oneOf:
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerID'
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerIdempotentIdentifier'
properties:
sync_enrichments:
$ref: '#/components/schemas/SynchronousEnrichmentsList'
transactions:
type: array
description: List of transactions belonging to the customer.
minItems: 1
items:
$ref: '#/components/schemas/CustomerTransactionV3'
transaction_windows:
$ref: '#/components/schemas/TransactionWindowArray'
IngestResponseV3SubTaskWithCustomerID:
title: With Customer ID
properties:
customer_id:
$ref: '#/components/schemas/CustomerID'
required:
- customer_id
IngestResponseV3SubTaskWithCustomerIdempotentIdentifier:
title: With Customer Idempotent Identifier
properties:
customer_idempotent_identifier:
type: string
description: |
An internal client identifier. This identifier can then be used in place of `X-Customer-Id` across Bud's endpoints.
required:
- customer_idempotent_identifier
schemas-TransactionForSyncIngest:
title: Transaction
type: object
description: A financial transaction
required:
- transaction_id
- account_id
- description
- amount
- credit_debit_indicator
- status
- date_time
- suggested_description
properties:
transaction_id:
type: string
description: Unique identifier for the transaction. May be mutable depending on original ingestion source.
account_id:
type: string
description: Identifier for the account associated with the transaction.
description:
type: string
description: Description of the transaction.
credit_debit_indicator:
type: string
description: Credit/Debit Indicator
enum:
- credit
- debit
status:
type: string
description: Status of the transaction. Defaults to booked.
enum:
- booked
- pending
- declined
suggested_description:
type: string
description: The description Bud suggests client apps show for a given transaction.
suggested_logo:
type: string
description: The logo Bud suggests client apps show for a given transaction.
transaction_type:
$ref: '#/components/schemas/BudTransactionType'
amount:
$ref: '#/components/schemas/BudAmount'
date_time:
type: string
description: Date of the transaction compliant with RFC3339.
value_date_time:
type: string
description: Date the assets involved in the transaction transferred compliant with RFC3339. For credits this is the date that the asset becomes available, for debits this is the date that the asset ceased to be available
enrichments:
$ref: '#/components/schemas/SyncEnrichments'
merchant_category_code:
type: string
description: |
A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245. An MCC is used to classify a business by the types of goods or services it provides.
tags:
type: array
description: |
A list of potential tags associated with the transaction after contextual enrichment, which can be used for filtering.
Region and client specific.
| Value | Description |
|:------------------------|:----------------------------------------------------------|
| `benefit` | A government/non-profit benefit transaction |
| `debt-collection` | A transaction associated with a known debt-collector |
| `loan` | A transaction associated with a loan |
| `hcst` | A transaction associated with a high cost short term loan |
| `income` | A transaction associated with income |
| `pending` | A transaction which has not been booked |
| `regular-transaction` | A transaction predicted to occur with a regular frequency |
| `subscription` | A transaction associated with a subscription service |
| `online` | A transaction associated with an online merchant |
items:
type: string
IngestV2SyncResponseData:
title: Enriched Customer Transactions
type: object
oneOf:
- $ref: '#/components/schemas/IngestResponseV3SubTaskWithCustomerID'
- $ref: '#/components/schemas/IngestResponseV3SubTaskWithCustomerIdempotentIdentifier'
required:
- enriched_transactions
properties:
enriched_transactions:
type: array
items:
$ref: '#/components/schemas/schemas-TransactionForSyncIngest'
IngestV2SyncMetadata:
title: Created Task Details
description: Metadata on the created task, including the task_id
type: object
required:
- task_id
properties:
task_id:
type: string
nullable: true
format: uuid
description: Can be used with the transaction status endpoint to retrieve the status of the full enriched process
next_url:
type: string
description: The path to call to obtain the current status of the task.
example: /v2/ingest/status/4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url_delay:
type: number
description: The time in milliseconds that the client should wait before trying to retrieve the current status of the task.
example: 500
IngestV2SyncResponse:
title: Ingest Transactions V2 Sync Response
type: object
allOf:
- $ref: '#/components/schemas/IngestV2Response'
- type: object
required:
- operation_id
- metadata
properties:
data:
type: array
items:
$ref: '#/components/schemas/IngestV2SyncResponseData'
metadata:
$ref: '#/components/schemas/IngestV2SyncMetadata'
ValidationError:
type: object
title: Validation Errors
required:
- operation_id
- code_id
- message
- errors
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
enum:
- failed_validation
message:
type: string
description: 'High level description on what has failed '
errors:
type: object
title: Map_of_customer_IDs
description: a map of customer IDs to transaction validation errors
properties:
missing_fields:
type: object
title: Map of transaction IDs
description: |
A map of transaction IDs to missing fields array.
If the transaction ID was missing use the request transaction array index to identify it.
See example
additionalProperties:
$ref: '#/components/schemas/ValidationMissing'
invalid_fields:
type: object
title: Map of transaction IDs
description: |
A map of transaction IDs to invalid fields array.
If the transaction ID was missing use the request transaction array index to identify it.
See example
additionalProperties:
$ref: '#/components/schemas/ValidationInvalid'
example:
operation_id: enrich_transactions_post
code_id: failed_validation
message: validation failure(s) in request payload
errors:
1db8c4b5-e5ae-429e-947b-6a4616ffc717:
missing_fields:
8b13ac45-9fe6-4c17-8c6d-b60ab2b4edad:
- description
- customer_id
ba466961-d623-4173-9001-2f6487a9a41e:
- customer_id
tx-1:
- transaction_id
578f24f2-5046-463a-bca6-239e0dfac7fa:
- amount
invalid_fields:
8b13ac45-9fe6-4c17-8c6d-b60ab2b4edad:
- date
ba466961-d623-4173-9001-2f6487a9a41e:
- date
TransactionSettlementV3Request:
type: array
items:
type: object
oneOf:
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerID'
- $ref: '#/components/schemas/IngestFirstPartyDataWithCustomerIdempotentIdentifier'
properties:
transactions:
type: array
items:
type: object
required:
- transaction_id
- date_time
properties:
transaction_id:
type: string
description: The unique identifier of a transaction to be booked.
date_time:
type: string
description: |
The datetime when the transaction transitioned to booked in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
TransactionSettlementV3Response:
title: Settle Transactions V3 Response
type: object
required:
- operation_id
- metadata
properties:
operation_id:
type: string
metadata:
type: object
required:
- task_id
properties:
task_id:
type: string
format: uuid
description: |
The task_id of the async settlement task.
This can be used to check the status and errors of the task using the __Retrieve Ingestion Task Status V3__ endpoint.
next_url:
type: string
description: The path to call to obtain the current status of the task.
example: /v2/ingest/status/4cef424c-1d7f-4cab-8be2-aee7e1774a00
next_url_delay:
type: number
description: The time in milliseconds that the client should wait before trying to retrieve the current status of the task.
example: 500
TransactionSettlementV3WebookBody:
title: Transaction Settlement Webhook Payload
type: object
description: |
The payload send to the client defined webhook (via the console) when a Book or Decline settlement task is Completed.
required:
- data
properties:
data:
type: object
required:
- event
- operation_id
- status
- task_id
properties:
event:
description: The type of settlement task that completed.
type: string
enum:
- first_party_ingester.transactions.booked
- first_party_ingester.transactions.declined
operation_id:
description: The operation ID of settlement task that completed.
type: string
enum:
- v3_ingest_transactions_book_post
- v3_ingest_transactions_decline_post
status:
description: The status of the settlement task that completed.
type: string
enum:
- Completed
- PartialCompleted
- Failed
task_id:
description: |
The task_id of the settlement task that completed.
This can be used to check full status and errors of the task using the __Retrieve Ingestion Task Status V3__ endpoint.
type: string
IngestTaskResult:
title: Ingestion Task Result
type: string
description: |
Indicates the outcome of the ingest task. Either success or various error codes:
| code | description |
| ---- | ----------- |
| success | Ingestion completed successfully. Data is now available. |
| validation_error | The request format is invalid. Please review the endpoint documentation for correct parameters and headers. |
| data_mapping_error | The data payload does not match the expected schema. Ensure your data aligns with the defined structure. |
| internal_error | Something went wrong on our side. Please retry your request later. |
| timed_out | The task did not complete in due time. |
IngestResponseV3SubTask:
title: Customer Ingest Task
description: A single customer ingest task status
type: object
oneOf:
- $ref: '#/components/schemas/IngestResponseV3SubTaskWithCustomerID'
- $ref: '#/components/schemas/IngestResponseV3SubTaskWithCustomerIdempotentIdentifier'
required:
- status
properties:
status:
title: Ingest Response Status
description: Ingest response status.
type: string
enum:
- Completed
- Failed
- Pending
result:
$ref: '#/components/schemas/IngestTaskResult'
error:
description: Any error messages describing why a sub task has failed.
type: object
additionalProperties: true
OverallIngestResponseStatus:
title: Ingest Task Overall Status
description: Ingest response status.
type: string
enum:
- Completed
- Pending
- Failed
- PartialCompleted
IngestStatusTaskMetadata:
title: Ingest Task Metadata
description: Expected response structure.
type: object
required:
- task_id
- status
properties:
task_id:
type: string
format: uuid
description: Unique task identifier.
status:
$ref: '#/components/schemas/OverallIngestResponseStatus'
result:
$ref: '#/components/schemas/IngestTaskResult'
ingest_request_id:
type: string
format: uuid
description: Unique identifier of the initial ingest request
ingest_route:
type: string
description: The endpoint used for this ingest task
enum:
- ingest_accounts_post
- ingest_transactions_post
- v2_ingest_accounts_post
- v2_ingest_transactions_post
- v3_ingest_transactions_book_post
- v3_ingest_transactions_decline_post
ingest_schema:
type: string
description: The account/transaction schema used for the ingest
enum:
- application/bud-accounts+json
- application/bud-transaction-v2+json
- application/bud-transaction-v3+json
next_url:
description: The URL to call to obtain the results of the task
type: string
next_url_delay:
description: Recommended delay in milliseconds before next call
type: number
IngestStatusV3Response:
title: Ingestion Task Status Response
type: object
description: Report on the status of an ingestion task
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
$ref: '#/components/schemas/IngestResponseV3SubTask'
metadata:
$ref: '#/components/schemas/IngestStatusTaskMetadata'
TaskNotFoundError:
type: object
title: Task Not Found
required:
- operation_id
- code_id
- message
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
message:
type: string
description: High level description on what has failed
example:
operation_id: ingest_transactions_get
code_id: not_found
message: Task not found
CustomersGetAllV3DataItem:
type: object
description: Representation of a Customer.
required:
- customer_id
- created_at
properties:
customer_id:
type: string
format: uuid
created_at:
type: string
description: Date and time at which the Customer has been registered (ISO 8601).
idempotent_identifier:
type: string
description: Client-assigned idempotent customer identifier (omitted if not present).
CustomersGetAllV3ResponseMetadata:
type: object
description: Metadata that defines token-based pagination of results.
required:
- results
properties:
next_page_token:
type: string
description: Page token for next part of the result set, omitted if there are no other pages.
results:
type: integer
description: The number of results returned.
CustomersGetAllV3Response:
title: List customers response
type: object
description: Expected response structure.
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
$ref: '#/components/schemas/CustomersGetAllV3DataItem'
metadata:
$ref: '#/components/schemas/CustomersGetAllV3ResponseMetadata'
CustomerContextType:
title: Customer Context Type
type: string
enum:
- personal
- business
description: |
The type of customer signed up:
| Value | Description |
|------------|-----------------------------------------|
| `personal` | Individuals with personal bank accounts |
| `business` | Businesses with business accounts |
CustomerContextRegion:
title: Customer Context Region
type: string
description: The region/country where the customer is located, format defined by ISO 3166 Alpha-2.
CustomerContextLocale:
title: Customer Context Locale
type: string
description: The locale/language, based on the region, format defined by BCP 47.
CustomerContextModels:
title: Customer Context Models
type: object
description: The configuration for Bud's enrichment models.
properties:
categorisation:
type: string
description: The name of the categorisation model to use for this customer at enrichment. See *List Categorisation Models V2* for available models.
CustomerContextRequest:
title: Customer Context
description: The context in which a customer is processed throughout the Bud platform.
type: object
properties:
type:
$ref: '#/components/schemas/CustomerContextType'
region:
$ref: '#/components/schemas/CustomerContextRegion'
locale:
$ref: '#/components/schemas/CustomerContextLocale'
models:
$ref: '#/components/schemas/CustomerContextModels'
IdempotentIdentifier:
title: Idempotent Identifier
description: An internal client identifier. If specified will ensure we only have one customer id per identifier.
type: string
ClientMetadata:
title: Client Metadata
description: A set of Client Metadata
type: object
properties:
idempotent_identifier:
$ref: '#/components/schemas/IdempotentIdentifier'
CustomerContextHostSecret:
title: Customer Context Host Secret
type: boolean
description: Determines whether the customer secret key should be stored with Bud, meaning the API consumer does not need to store this and provide it on subsequent API calls related to that customer.
CustomerContext:
title: Customer Context
description: The context in which a customer is processed throughout the Bud platform.
type: object
properties:
type:
$ref: '#/components/schemas/CustomerContextType'
region:
$ref: '#/components/schemas/CustomerContextRegion'
locale:
$ref: '#/components/schemas/CustomerContextLocale'
host_secret:
$ref: '#/components/schemas/CustomerContextHostSecret'
models:
$ref: '#/components/schemas/CustomerContextModels'
CustomerCreatedV3:
title: Customer Created V3
type: object
required:
- customer_id
- customer_context
properties:
customer_id:
description: A unique identifier for a Customer, as registered on Bud's platform
type: string
format: uuid
customer_secret:
description: A unique Customer encryption key used to encrypt their data on the Bud platform. Only returned if the secret is *not* hosted on the Bud Platform.
type: string
customer_context:
$ref: '#/components/schemas/CustomerContext'
client_metadata:
$ref: '#/components/schemas/ClientMetadata'
CustomerCreatedV3Metadata:
title: Customer Created V3 Metadata
type: object
properties:
created_at:
type: string
format: date-time
description: The date and time the customer was created. Format ISO 8601.
CustomerCreateV3Response:
title: Create Customer V3 Response
type: object
description: Expected response structure.
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/CustomerCreatedV3'
metadata:
$ref: '#/components/schemas/CustomerCreatedV3Metadata'
CreateCustomersV3BatchPayload:
title: Create Customers V3 Batch Payload
type: object
properties:
number_of_customers:
description: The number of customers to create (register) on Bud's platform in a single request.
type: integer
default: 1
maximum: 200
customer_context:
$ref: '#/components/schemas/CustomerContextRequest'
CreateCustomersV3BatchResponse:
title: Create Customers V3 Batch Response
type: object
description: Expected response structure.
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
description: An array of Customer Created objects.
items:
$ref: '#/components/schemas/CustomerCreatedV3'
metadata:
$ref: '#/components/schemas/CustomerCreatedV3Metadata'
CustomerDeleteV3:
title: Customer Delete V3
type: object
required:
- task_id
properties:
task_id:
$ref: '#/components/schemas/TaskId'
CustomerDeleteV3Response:
title: Delete Customer V3 Response
type: object
description: Expected response structure.
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/CustomerDeleteV3'
metadata:
$ref: '#/components/schemas/AsyncTaskMetadata'
DeleteResultCodes:
type: string
description: The result of the operation. Either success or failed.
enum:
- success
- failed
TaskCustomerDeleteV3:
title: Customer Delete Task Response
type: object
description: Result of GET customer delete taskId
required:
- task_id
properties:
result:
$ref: '#/components/schemas/DeleteResultCodes'
task_id:
$ref: '#/components/schemas/TaskId'
TaskCustomerDeleteV3MetaData:
title: Task Status Metadata
type: object
description: Standard metadata response from the Customer Delete V3
required:
- status
properties:
status:
type: string
description: The status of the job associated with the specified task id
enum:
- Completed
- Pending
- Failed
next_url:
type: string
description: The url to try next if the `status` property returned is `Pending`
next_url_delay:
type: number
description: The time in milliseconds that the client should wait before polling the relevant GET endpoint with the above task id if the `status` property returned is `Pending`
CustomerDeleteV3StatusResponse:
title: Customer Delete Status Response
type: object
description: Expected response structure
required:
- operation_id
- metadata
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/TaskCustomerDeleteV3'
metadata:
$ref: '#/components/schemas/TaskCustomerDeleteV3MetaData'
CustomerCreateResponse:
title: Create Customer Response
type: object
description: Expected response structure.
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
required:
- customer_id
- customer_secret
- customer_context
properties:
customer_id:
description: A unique identifier for a Customer, as registered on Bud's platform.
type: string
format: uuid
customer_secret:
description: An unique Customer encryption key used to encrypt their data on the Bud platform. Please note that this key is not held by Bud, and is required in the header of any endpoint that involves reading Customer data stored on the Bud platform.
type: string
customer_context:
$ref: '#/components/schemas/CustomerContext'
CreateCustomersPayload:
title: Create Customers Payload
type: object
properties:
number_of_customers:
description: The number of customers to create (register) on Bud's platform in a single request.
type: integer
default: 1
maximum: 200
customer_context:
$ref: '#/components/schemas/CustomerContext'
CustomerCreated:
title: Customer Created
type: object
required:
- customer_id
- customer_secret
- customer_context
properties:
customer_id:
description: A unique identifier for a Customer, as registered on Bud's platform
type: string
format: uuid
customer_secret:
description: An unique Customer encryption key used to encrypt their data on the Bud platform. Please note that this key is not held by Bud, and is required in the header of any endpoint that involves reading Customer data stored on the Bud platform.
type: string
customer_context:
$ref: '#/components/schemas/CustomerContext'
CustomersCreateResponse:
title: Create Customers Response
type: object
description: Expected response structure.
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
description: An array of Customer Created objects
items:
$ref: '#/components/schemas/CustomerCreated'
metadata:
$ref: '#/components/schemas/ResultsMetadata'
CustomerContextResponse:
title: Customer Context Response
description: Customer context response.
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
data:
$ref: '#/components/schemas/CustomerContext'
UpdateCustomerContextRequest:
title: Update Customer Context Request
type: object
description: Expected request payload structure.
properties:
region:
$ref: '#/components/schemas/CustomerContextRegion'
locale:
$ref: '#/components/schemas/CustomerContextLocale'
models:
$ref: '#/components/schemas/CustomerContextModels'
UpdateCustomerContextResponse:
title: Customer Context Update Response
description: Customer context update response.
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
data:
title: Updated Customer Context
type: object
properties:
region:
$ref: '#/components/schemas/CustomerContextRegion'
locale:
$ref: '#/components/schemas/CustomerContextLocale'
models:
$ref: '#/components/schemas/CustomerContextModels'
schemas-CategorisationModel:
title: Categorisation Model
type: object
description: Bud categorisation model.
required:
- name
- description
properties:
name:
type: string
description: Name of the model.
description:
type: string
description: Description of the model & use-cases it provides.
deprecated:
type: boolean
description: A flag to mark a particular model version as deprecated (this field is omitted if the model is not deprecated).
GetModelsResponse:
title: Models Response
required:
- operation_id
- data
properties:
operation_id:
type: string
data:
type: array
items:
$ref: '#/components/schemas/schemas-CategorisationModel'
CategoriesFlat:
title: Category List
type: object
description: A list of all the available categories and subcategories.
properties:
categories:
type: array
description: List of all the available categories.
items:
type: string
subcategories:
type: array
description: List of all the available subcategories.
items:
type: string
CategoriesMap:
title: Category Map
description: A map of all the available categories and respective subcategories
type: array
items:
title: Category
description: A single category and its respective subcategories.
type: object
properties:
name:
title: Category Name
description: The name of the category.
type: string
labels:
title: Labels
description: |
Cross category labels used in our engage products, all subcategories will inherit the labels of their parents.
You can use these labels to understand how certain category determinations are being made, such as if a category considered essential.
type: array
example:
- essential
items:
type: string
subcategories:
title: Subcategories
description: The respective subcategories for the given category.
type: array
items:
title: subcategory
description: A subcategory that belongs to the given category.
type: object
properties:
name:
title: Subcategory Name
description: The name of the subcategory.
type: string
labels:
title: Labels
description: |
Cross category labels used in our engage products.
You can use these labels to understand how certain category determinations are being made, such as if a category considered essential.
type: array
example:
- essential
items:
type: string
GetCategoriesV2Response:
title: Categories Response
type: object
description: Expected response structure for the get categories endpoint.
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
oneOf:
- $ref: '#/components/schemas/CategoriesFlat'
- $ref: '#/components/schemas/CategoriesMap'
metadata:
type: object
required:
- model
properties:
model:
$ref: '#/components/schemas/schemas-CategorisationModel'
TotalAmountWithTrxCount:
type: object
title: Amount with transaction count
description: Amount of money in the cash transaction entry, including the number of transactions used in the calculation.
required:
- transaction_count
- amount
properties:
amount:
$ref: '#/components/schemas/BudAmount'
transaction_count:
type: integer
CategoriesTotalV2L2:
title: Categories Totals Response
type: object
required:
- name
properties:
credit_total:
type: array
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
debit_total:
type: array
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
name:
type: string
description: Category id as slug.
CategoriesTotalV2:
type: object
required:
- name
properties:
credit_total:
type: array
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
debit_total:
type: array
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
name:
type: string
description: Category id as slug.
l2_totals:
type: array
description: L2 category totals.
items:
$ref: '#/components/schemas/CategoriesTotalV2L2'
CategoriesTotalV2Response:
title: Categories Totals Response
type: object
description: ''
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
nullable: true
type: array
items:
$ref: '#/components/schemas/CategoriesTotalV2'
metadata:
type: object
required:
- from
- to
properties:
from:
type: string
example: '2023-05-21T07:20:50.52Z'
description: |
RFC3339 compliant date stamp indicating the beginning of the transaction window used in this calculation
to:
type: string
example: '2023-05-21T07:20:50.52Z'
description: |
RFC3339 compliant date stamp indicating the end of the transaction window used in this calculation
credit_total:
type: array
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
description: |
The total across credit transactions from all included categories
debit_total:
type: array
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
description: |
The total across debit transactions from all included categories
CategoriesTotalTrendsV2Response:
type: object
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
type: object
required:
- data
- to
- from
properties:
data:
type: array
items:
$ref: '#/components/schemas/CategoriesTotalV2'
to:
type: string
example: '2023-05-21T07:20:50.52Z'
description: RFC 3339 Compliant date stamp indicating the beginning of the transaction window used in this calculation
from:
type: string
example: '2023-05-21T07:20:50.52Z'
description: RFC 3339 Compliant date stamp indicating the end of the transaction window used in this calculation
PercentageCurrency:
type: object
title: Percentage with relevant currency
description: A percentage for the associated currency
required:
- percentage
- currency
properties:
percentage:
type: number
currency:
type: string
EssentialSpendStatisticsResponse:
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
enum:
- aggregations_v2_totals_essential_statistics_get
data:
type: object
required:
- essential_spend
- nonessential_spend
- essential_percentage_overall_spend
- nonessential_percentage_overall_spend
properties:
essential_spend:
type: array
description: Sum of all debit transactions categorized with an essential labeled category by currency
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
nonessential_spend:
description: Sum of all debit transactions categorized with an nonessential labeled category by currency
type: array
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
essential_percentage_overall_spend:
type: array
description: essential percentage of essential + nonessential debit transactions by currency
items:
$ref: '#/components/schemas/PercentageCurrency'
nonessential_percentage_overall_spend:
type: array
description: nonessential percentage of essential + nonessential debit transactions by currency
items:
$ref: '#/components/schemas/PercentageCurrency'
metadata:
type: object
required:
- from
- to
properties:
from:
type: string
example: '2023-05-21T07:20:50.52Z'
description: |
RFC3339 compliant date stamp indicating the beginning of the transaction window used in this calculation
to:
type: string
example: '2023-05-21T07:20:50.52Z'
description: |
RFC3339 compliant date stamp indicating the end of the transaction window used in this calculation
schemas-Merchant:
title: Bud Merchant Object
type: object
description: Details regarding a merchant associated with a transaction
required:
- id
- name
- logo
properties:
id:
type: string
description: Identifier for the detected merchant
name:
type: string
description: Display name for the detected merchant
logo:
type: string
description: URL for logo of the detected merchant
MerchantTotalV2:
type: object
title: Merchant Total
required:
- merchant
- total_debit
- total_credit
- transaction_count
- credit_transaction_count
- debit_transaction_count
properties:
merchant:
$ref: '#/components/schemas/schemas-Merchant'
total_debit:
allOf:
- title: Total Debit
description: Total debit amount of all transactions identified with the named merchant
- $ref: '#/components/schemas/BudAmount'
total_credit:
allOf:
- title: Total Credit
description: Total credit amount of all transactions identified with the named merchant
- $ref: '#/components/schemas/BudAmount'
transaction_count:
type: number
title: Transaction Count
description: Total number of transactions identified with the named merchant
credit_transaction_count:
type: number
title: Credit Transaction Count
description: Total number of credit transactions identified with the named merchant
debit_transaction_count:
type: number
title: Debit Transaction Count
description: Total number of debit transactions identified with the named merchant
LegacyBudDateRangeMetadata:
title: Metadata
type: object
required:
- from
- to
properties:
from:
type: string
description: |
The date from when results were retrieved in the format [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html).
This is either populated with the default value used when retrieving the results, or the user specified parameter.
Example: `2023-01-17`
to:
type: string
description: |
The date up to when results were retrieved in the format [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html).
This is either populated with the default value used when retrieving the results, or the user specified parameter.
Example: `2023-03-17`
TransactionsResultsMetadata:
title: Metadata
description: Metadata associated with the response schema
allOf:
- $ref: '#/components/schemas/LegacyBudDateRangeMetadata'
- type: object
required:
- results
properties:
results:
type: number
description: Number of results returned
MerchantTotalsMetadataV2:
allOf:
- $ref: '#/components/schemas/TransactionsResultsMetadata'
- type: object
title: Metadata
properties:
categories_included:
description: Categories included in total (from `X-Include-Categories`)
type: array
items:
type: string
categories_excluded:
description: Categories excluded from total (from `X-Exclude-Categories`)
type: array
items:
type: string
credit_total:
type: array
description: The total credit amount over this period by currency
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
debit_total:
type: array
description: The total debit amount over this period by currency
items:
$ref: '#/components/schemas/TotalAmountWithTrxCount'
MerchantTotalsResponseV2:
title: Merchant Totals
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
$ref: '#/components/schemas/MerchantTotalV2'
metadata:
$ref: '#/components/schemas/MerchantTotalsMetadataV2'
AccountV3Balance:
type: object
title: Balance
required:
- date
- amount
- credit_debit_indicator
properties:
date:
type: string
description: |
The date when the balance was last updated in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
amount:
$ref: '#/components/schemas/BudAmount'
credit_debit_indicator:
type: string
description: The credit or debit state of the given balance
enum:
- credit
- debit
AccountV3Balance_WithType:
type: object
title: Balance
required:
- date
- amount
- credit_debit_indicator
properties:
date:
type: string
description: |
The date when the balance was last updated in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
amount:
$ref: '#/components/schemas/BudAmount'
credit_debit_indicator:
type: string
description: The credit or debit state of the given balance
enum:
- credit
- debit
type:
type: string
description: |
The type for the given balance
Currently supported values include (but are not necessarily limited to):
- `closing_available`
- `closing_booked`
- `closing_cleared`
- `expected`
- `forward_available`
- `information`
- `interim_available`
- `interim_booked`
- `interim_cleared`
- `opening_available`
- `opening_booked`
- `opening_cleared`
- `previously_closed_booked`
enum:
- closing_available
- closing_booked
- closing_cleared
- expected
- forward_available
- information
- interim_available
- interim_booked
- interim_cleared
- opening_available
- opening_booked
- opening_cleared
- previously_closed_booked
AccountV3CreditLine:
type: object
title: Credit_Line
required:
- date
- amount
properties:
date:
type: string
description: |
The date when the credit line was last updated in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
amount:
$ref: '#/components/schemas/BudAmount'
AccountV3CreditLine_WithType:
type: object
title: Credit_Line
required:
- date
- type
- amount
properties:
date:
type: string
description: |
The date when the credit line was last updated in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
type:
type: string
description: |
The type of the given credit line.
Currently supported values include (but are not necessarily limited to):
- `available`
- `credit`
- `emergency`
- `pre_agreed`
- `temporary`
amount:
$ref: '#/components/schemas/BudAmount'
AccountV3:
title: Account
type: object
required:
- account_id
- currency
- suggested_name
properties:
account_id:
type: string
description: |
A unique id associated with the account.
Example: `sdb4eRMaad8XVEvdIoISOQ`
currency:
$ref: '#/components/schemas/BudCurrency'
suggested_name:
type: string
description: The name Bud suggests client apps show for the account.
holders:
type: array
description: |
The account holder(s).
items:
title: Account_Holder
type: object
properties:
name:
type: string
description: |
The name of the given account holder.
Example: `John Smith`
relationship:
type: string
description: |
The relationship that the individual holder has with the account. If parties data is not present, this will always be `unknown`.
Currently supported values include (but are not necessarily limited to):
- `sole`
- `joint`
- `delegate`
- `unknown`
account_name:
type: string
description: |
The name associated with the account, this is often a friendly name assigned to the account to make it easier to refer to.
Example: `Household Savings Account`
Not present if empty.
account_type:
type: string
description: |
The type of account.
Currently supported values include (but are not necessarily limited to):
- `auto_loan`
- `boat_loan`
- `brokerage`
- `business_loan`
- `certificate_of_deposit`
- `charge_card`
- `checking_account`
- `credit_card`
- `current_account`
- `disability_insurance`
- `e_money`
- `health_insurance`
- `home_equity_loan`
- `investment`
- `ira`
- `liability_insurance`
- `life_insurance`
- `line_of_credit`
- `loan`
- `money_market`
- `mortgage`
- `other`
- `personal_loan`
- `pre_paid_card`
- `property_insurance`
- `roth`
- `rv_loan`
- `savings`
- `student_loan`
- `travel_insurance`
- `vehicle_insurance`
Not present if empty.
usage_type:
type: string
description: |
The intended usage of the account.
Currently supported values include (but are not necessarily limited to):
- `personal`
- `business`
Not present if empty.
status:
type: string
description: |
The status of the account. If this field is not present, then the account is considered open.
Currently supported values include (but are not necessarily limited to):
- `closed`
opening_date_time:
type: string
format: date-time
description: The datetime the account was opened in the format [RFC 3339]
closed_at:
type: string
format: date-time
description: |
The datetime the account was closed in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
If the account is not closed, this field will not be present.
provider:
type: string
description: |
The account's provider, this is usually the bank or building society the account is held with.
Example: `Nationwide`
Not present if empty.
provider_display_name:
type: string
description: |
The display name for the account's provider.
Not present if empty.
provider_logo:
type: string
description: |
A link to an image for the accounts provider's logo.
Not present if empty.
account_category:
type: string
description: |
The account category that the account type is a part of
Currently supported values include (but are not necessarily limited to):
- `credit`
- `depository`
- `insurance`
- `investment`
- `loan`
- `other`
identifiers:
type: object
description: These are wellknown fields which uniquely identify the account.
properties:
us_account_number:
type: string
description: |
The account number associated with this account
Example: `...3750`
uk_sort_code:
type: string
description: |
A six digit number identifying the UK bank or building society the account is held with. This is usually supplied alongside a `uk_account_number` to uniquely identify the account.
Example: `601613`
uk_account_number:
type: string
description: |
An eight digit number uniquely identifying the account for the UK bank or building society the account is held with. This is usually supplied alongside a `uk_sort_code` to uniquely identify the account from accounts with other UK banks or building societies.
Example: `31926819`
nz_account_number:
type: string
description: |
A sixteen digit number uniquely identifying the account and New Zealand bank the account is held with.
Example: `1212341234567123`
iban:
type: string
description: |
A thirty-four character alphanumerical code (ISO 13616), internationally and uniquely identifying the account.
Example: `GB29NWBK60161331926819`
pan:
type: string
description: |
A number between 14 and 19 digits that uniquely identifies the account, this is usually the number printed on the card assigned to the account.
Example: `4444333322221111`
balances:
type: object
description: |
The balances ingested for the account.
> 📘 Note
>
> Normalised balances are derived from ingested data, therefore we're unable to guarantee that either a `booked` or `pending` balance will always be present. Where possible we will look to return both.
properties:
booked:
description: |
The booked balance for the account at the given date.
This field is not guaranteed to be present. It will only exist if a booked balance was found from ingested balances.
allOf:
- $ref: '#/components/schemas/AccountV3Balance'
pending:
description: |
The pending balance for the account at the given date.
This field is not guaranteed to be present. It will only exist if a pending balance was found from ingested balances.
allOf:
- $ref: '#/components/schemas/AccountV3Balance'
all_balances:
type: array
description: |
A granular breakdown of balance types ingested for the account.
**NOTE: Only included if the `include_all_balances` query parameter is set.**
items:
$ref: '#/components/schemas/AccountV3Balance_WithType'
credit_lines:
type: object
title: Credit Lines
description: |
The latest credit limit available for the account.
This field will only be present if the credit limit was found from ingested balances.
properties:
limit:
type: object
description: |
The credit limit for the account at the given date.
This field will only be present if the credit limit was found from ingested balances.
allOf:
- $ref: '#/components/schemas/AccountV3CreditLine'
all_credit_lines:
type: array
description: |
All credit lines stored for the account.
Only included if the `include_all_balances` query parameter is set
items:
$ref: '#/components/schemas/AccountV3CreditLine_WithType'
transaction_windows:
type: array
title: Transaction Windows
description: |
The transaction windows indicate for which periods we have full coverage of transactions ingested for the account.
Not present if no transaction data has been ingested.
items:
type: object
title: Transaction Window
required:
- from
- to
properties:
from:
type: string
description: A [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) datetime recording the start of the window
to:
type: string
description: A [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) datetime recording the end of the window
ListAccountsV3Response:
title: Retrieve Accounts Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- financial_v3_accounts_get
data:
type: array
items:
$ref: '#/components/schemas/AccountV3'
metadata:
type: object
required:
- parameters
- results
properties:
parameters:
type: object
properties:
currencies:
description: The Currency values supplied in the request to generate the given result set.
type: array
items:
$ref: '#/components/schemas/BudCurrency'
account_types:
description: |
The Account Type values supplied in the request to generate the given result set.
Currently supported values include (but are not necessarily limited to):
- `charge_card`
- `credit_card`
- `current_account`
- `e_money`
- `investment`
- `loan`
- `mortgage`
- `other`
- `pre_paid_card`
- `savings`
type: array
items:
type: string
usage_types:
description: |
The Usage Type values supplied in the request to generate the given result set.
Currently supported values include (but are not necessarily limited to):
- `personal`
- `business`
type: array
items:
type: string
holder_types:
description: |
The Holder Type values supplied in the request to generate the given result set.
Currently supported values include (but are not necessarily limited to):
- `sole`
- `joint`
- `delegate`
- `unknown`
type: array
items:
type: string
providers:
description: The Provider values supplied in the request to generate the given result set.
type: array
items:
type: string
include_all_balances:
type: boolean
description: All balances and credit lines stored for the accounts are returned
results:
type: number
description: The number of accounts returned in the results
RetrieveAccountByIDV3Response:
title: Retrieve Accounts by ID Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- financial_v3_accounts_account_id_get
data:
$ref: '#/components/schemas/AccountV3'
metadata:
type: object
required:
- parameters
- results
properties:
parameters:
type: object
properties:
currencies:
description: The Currency values supplied in the request to generate the given result set.
type: array
items:
$ref: '#/components/schemas/BudCurrency'
account_types:
description: |
The Account Type values supplied in the request to generate the given result set.
Currently supported values include (but are not necessarily limited to):
- `charge_card`
- `credit_card`
- `current_account`
- `e_money`
- `investment`
- `loan`
- `mortgage`
- `other`
- `pre_paid_card`
- `savings`
type: array
items:
type: string
usage_types:
description: |
The Usage Type values supplied in the request to generate the given result set.
Currently supported values include (but are not necessarily limited to):
- `personal`
- `business`
type: array
items:
type: string
holder_types:
description: |
The Holder Type values supplied in the request to generate the given result set.
Currently supported values include (but are not necessarily limited to):
- `sole`
- `joint`
- `delegate`
- `unknown`
type: array
items:
type: string
providers:
description: The Provider values supplied in the request to generate the given result set.
type: array
items:
type: string
include_all_balances:
type: boolean
description: All balances and credit lines stored for the accounts are returned
results:
type: integer
description: The number of accounts returned in the results
TransactionDatesV3:
title: Account Transaction Date
type: object
required:
- account_id
- first_transaction_date
- last_transaction_date
properties:
account_id:
type: string
description: |
A unique id associated with the account.
Example: `sdb4eRMaad8XVEvdIoISOQ`
first_transaction_date:
type: string
format: date-time
description: The date of the first transaction that bud has stored for this account.
last_transaction_date:
type: string
format: date-time
description: The date of the last transaction that bud has stored for this account.
ListAccountTransactionDatesV3Response:
title: Retrieve Transaction Dates Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- financial_v3_accounts_transaction_dates_get
data:
type: array
items:
$ref: '#/components/schemas/TransactionDatesV3'
metadata:
type: object
required:
- results
properties:
results:
type: number
description: The number of accounts returned in the results
first_transaction_date:
type: string
format: date-time
description: The first transaction date across all accounts returned in the results
last_transaction_date:
type: string
format: date-time
description: The last transaction date across all accounts returned in the results
BalanceV3Amount:
title: Balance amount
description: A representation of both the amount and the credit/debit indicator
required:
- amount
- credit_debit_indicator
properties:
amount:
$ref: '#/components/schemas/BudAmount'
credit_debit_indicator:
type: string
description: Indication as to whether the balance is in credit or debit
enum:
- credit
- debit
BalanceOverTimeV3DataPoint:
title: Balance Over Time Data-Point
description: A single record of the balance at the end of the given date.
type: object
required:
- date
- booked
- pending
properties:
date:
type: string
description: |
The date of the given balance in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-03-17T23:59:59Z`
- `2023-03-17T23:59:59-08:00`
booked:
description: The current balance of the account
$ref: '#/components/schemas/BalanceV3Amount'
pending:
description: The balance of the account if all pending transactions have settled.
$ref: '#/components/schemas/BalanceV3Amount'
BudDateRangeMetadata:
title: Metadata
type: object
required:
- from
- to
properties:
from:
type: string
description: |
The date from when results were retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
This is either populated with the default value used when retrieving the results, or the user specified parameter.
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
to:
type: string
description: |
The date up to when results were retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
This is either populated with the default value used when retrieving the results, or the user specified parameter.
Examples:
- `2023-03-17T17:29:51Z`
- `2023-03-17T17:29:51-08:00`
GetBalancesV3Response:
title: Get Balances Response
type: object
required:
- operation_id
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
type: object
required:
- balances
properties:
account_id:
type: string
description: Identifier of the accounts from which the balances have been calculated
balances:
type: array
items:
$ref: '#/components/schemas/BalanceOverTimeV3DataPoint'
metadata:
type: object
properties:
accounts:
description: This is a hashmap representing account_ids and metadata about the results returned from the balances endpoint
additionalProperties:
description: Hashmap of an account_id returned from the balances endpoint
allOf:
- $ref: '#/components/schemas/BudDateRangeMetadata'
- type: object
properties:
balance_count:
type: number
description: The number of balances returned for the account
- type: object
properties:
min_balance:
description: The minimum balance in the returned period
$ref: '#/components/schemas/BudAmount'
- type: object
properties:
max_balance:
description: The maximum balance in the returned period
$ref: '#/components/schemas/BudAmount'
parameters:
title: The parameters used to calculated balances
allOf:
- $ref: '#/components/schemas/BudDateRangeMetadata'
- type: object
properties:
granularity:
type: string
description: |
The granularity that the balances have been retrieved for.
Currently supported values include (but are not necessarily limited to):
- `daily`
- `weekly`
- `biweekly`
- `monthly`
- `quarterly`
- `six_monthly`
- `annually`
GetBalancesForAccountIDV3Response:
title: Get Balances For Account ID Response
type: object
required:
- operation_id
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
$ref: '#/components/schemas/BalanceOverTimeV3DataPoint'
metadata:
type: object
properties:
accounts:
description: Metadata about the response for the given account_id
allOf:
- $ref: '#/components/schemas/BudDateRangeMetadata'
- type: object
properties:
balance_count:
type: number
description: The number of balances returned for the account
- type: object
properties:
min_balance:
description: The minimum balance in the returned period
$ref: '#/components/schemas/BudAmount'
- type: object
properties:
max_balance:
description: The maximum balance in the returned period
$ref: '#/components/schemas/BudAmount'
parameters:
allOf:
- $ref: '#/components/schemas/BudDateRangeMetadata'
- type: object
properties:
granularity:
type: string
description: The granularity that the balances have been retrieved for.
account_id:
type: string
description: The account ID the balances have been retrieved for.
BadRequestNotFoundResponse:
title: Bad Request Not Found Response
type: object
required:
- operation_id
- code_id
- message
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
code_id:
type: string
description: A descriptive enough string that is linked to the reason for the error.
message:
type: string
description: An actual user friendly error message.
AuthorisedPaymentItem:
title: Authorised Payment
description: An authorised payment item.
type: object
required:
- credit_debit_indicator
- amount
- date
- type
properties:
type:
type: string
description: |
The type of the transaction.
Examples:
- `previous_payment`
- `first_payment`
- `next_payment`
- `final_payment`
- `schedule_payment`
credit_debit_indicator:
type: string
description: To describe whether the transaction is debit or credit.
enum:
- debit
amount:
$ref: '#/components/schemas/BudAmount'
date:
type: string
example: '2023-05-21T07:20:50.52Z'
description: |
The date of the payment in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
AuthorisedPayment:
title: Authorised Payment
description: An authorised payment item.
type: object
required:
- id
- type
- account_id
- reference
- status
- name
properties:
id:
type: string
description: |
The id for the authorised payment.
Example: `d23fcaa3-8ac0-43ba-a44d-d7c41935f76f`
type:
type: string
description: |
The type of the authorised payment.
Currently supported values include (but are not necessarily limited to):
- direct_debit
account_id:
type: string
description: |
The unique id associated with the account.
example: `22289`
reference:
type: string
description: |
The reference associated with the authorised payment.
Example: `Streaming subscription`
status:
type: string
description: |
The status of the authorised payment.
Currently supported values include (but are not necessarily limited to):
- `active``
- `inactive`
- `cancelled`
- `expired`
- `suspended`
- `unknown`
name:
type: string
description: |
The name of the payment.
Example: `XY Club entrance fee"
frequency:
type: string
description: |
The frequency of the authorised payment.
Currently supported values include (but are not necessarily limited to):
- `intra_day`
- `daily`
- `working_daily`
- `weekly`
- `biweekly`
- `four_weekly`
- `monthly`
- `alternate_monthly`
- `two_monthly`
- `quarterly`
- `four_monthly`
- `five_monthly`
- `six_monthly`
- `annually`
- `adhoc`
- `unknown`
details:
type: array
description: Provides more details for the authorised payment.
items:
$ref: '#/components/schemas/AuthorisedPaymentItem'
GetAuthorisedPaymentsV2Response:
title: Retrieve AuthorisedPayments V2 Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- financial_v2_authorised_payments_get
data:
type: array
items:
$ref: '#/components/schemas/AuthorisedPayment'
metadata:
type: object
required:
- results
properties:
results:
description: The number of results returned.
type: integer
next_page_token:
description: Token is present if you have more pages.
type: string
AccountV2:
title: Account
type: object
required:
- account_id
- currency
properties:
account_id:
type: string
description: |
A unique id associated with the account.
Example: `sdb4eRMaad8XVEvdIoISOQ`
currency:
$ref: '#/components/schemas/BudCurrency'
holder:
title: Account_Holder
description: |
The account holder. This field is only present if parties data **is not** available.
Parties data will only be present if you are a Check customer, and the provider is support by Check.
Providers that support Check can be found in the Connect coverage table in Guides, under Connect.
type: object
properties:
name:
type: string
description: |
The name of the given account holder.
Example: `John Smith`
relationship:
type: string
description: |
The relationship that the individual holder has with the account. If parties data is not present, this will always be `unknown`.
Currently supported values include (but are not necessarily limited to):
- `sole`
- `joint`
- `delegate`
- `unknown`
holders:
type: array
description: |
The account holders. This field is only present if parties data **is** available.
Parties data will only be present if you are a Check customer, and the provider is supported by Check.
Providers that support Check can be found in the Connect coverage table in Guides, under Connect.
items:
title: Account_Holder
type: object
properties:
name:
type: string
description: |
The name of the given account holder.
Example: `John Smith`
relationship:
type: string
description: |
The relationship that the individual holder has with the account. If parties data is not present, this will always be `unknown`.
Currently supported values include (but are not necessarily limited to):
- `sole`
- `joint`
- `delegate`
- `unknown`
account_name:
type: string
description: |
The name associated with the account, this is often a friendly name assigned to the account to make it easier to refer to.
Example: `Household Savings Account`
account_type:
type: string
description: |
The type of account.
Currently supported values include (but are not necessarily limited to):
- `charge_card`
- `credit_card`
- `current_account`
- `e_money`
- `investment`
- `loan`
- `mortgage`
- `other`
- `pre_paid_card`
- `savings`
usage_type:
type: string
description: |
The intended usage of the account.
Currently supported values include (but are not necessarily limited to):
- `personal`
- `business`
status:
type: string
description: |
The status of the account. If this field is not present, then the account is considered open.
Currently supported values include (but are not necessarily limited to):
- `closed`
closed_at:
type: string
description: |
The datetime the account was closed in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
If the account is not closed, this field will not be present.
provider:
type: string
description: |
The account's provider, this is usually the bank or building society the account is held with.
Example: `Nationwide`
identifiers:
type: object
description: These are wellknown fields which uniquely identify the account.
properties:
uk_sort_code:
type: string
description: |
A six digit number identifying the UK bank or building society the account is held with. This is usually supplied alongside a `uk_account_number` to uniquely identify the account.
Example: `601613`
uk_account_number:
type: string
description: |
An eight digit number uniquely identifying the account for the UK bank or building society the account is held with. This is usually supplied alongside a `uk_sort_code` to uniquely identify the account from accounts with other UK banks or building societies.
Example: `31926819`
nz_account_number:
type: string
description: |
A sixteen digit number uniquely identifying the account and New Zealand bank the account is held with.
Example: `1212341234567123`
iban:
type: string
description: |
A thirty-four character alphanumerical code (ISO 13616), internationally and uniquely identifying the account.
Example: `GB29NWBK60161331926819`
pan:
type: string
description: |
A number between 14 and 19 digits that uniquely identifies the account, this is usually the number printed on the card assigned to the account.
Example: `4444333322221111`
balances:
type: array
title: Balances
description: The latest balances for the account.
items:
type: object
title: Balance
required:
- date
- type
- amount
- credit_debit_indicator
properties:
date:
type: string
description: |
The date when the balance was last updated in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
type:
type: string
description: |
The type for the given balance
Currently supported values include (but are not necessarily limited to):
- `closing_available`
- `closing_booked`
- `closing_cleared`
- `expected`
- `forward_available`
- `information`
- `interim_available`
- `interim_booked`
- `interim_cleared`
- `opening_available`
- `opening_booked`
- `opening_cleared`
- `previously_closed_booked`
amount:
$ref: '#/components/schemas/BudAmount'
credit_debit_indicator:
type: string
description: The credit or debit state of the given balance
enum:
- credit
- debit
transaction_windows:
type: array
title: Transaction Windows
description: |
The transaction windows indicate for which periods we have full coverage of transactions ingested for the account.
items:
type: object
title: Transaction Window
required:
- from
- to
properties:
from:
type: string
description: A [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) datetime recording the start of the window
to:
type: string
description: A [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) datetime recording the end of the window
credit_lines:
type: array
title: Credit Lines
description: The latest lines of credit available to the account. This is typically a representation of the overdraft or credit limits.
items:
type: object
title: Credit_Line
required:
- date
- type
- amount
properties:
date:
type: string
description: |
The date when the credit line was last updated in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
type:
type: string
description: |
The type of the given credit line.
Currently supported values include (but are not necessarily limited to):
- `available`
- `credit`
- `emergency`
- `pre_agreed`
- `temporary`
amount:
$ref: '#/components/schemas/BudAmount'
ListAccountsV2Response:
title: Retrieve Accounts Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- financial_v2_accounts
data:
type: array
items:
$ref: '#/components/schemas/AccountV2'
metadata:
type: object
required:
- parameters
- result_count
properties:
parameters:
type: object
properties:
currencies:
description: The Currency values supplied in the request to generate the given result set.
type: array
items:
$ref: '#/components/schemas/BudCurrency'
account_types:
description: |
The Account Type values supplied in the request to generate the given result set.
Currently supported values include (but are not necessarily limited to):
- `charge_card`
- `credit_card`
- `current_account`
- `e_money`
- `investment`
- `loan`
- `mortgage`
- `other`
- `pre_paid_card`
- `savings`
type: array
items:
type: string
usage_types:
description: |
The Usage Type values supplied in the request to generate the given result set.
Currently supported values include (but are not necessarily limited to):
- `personal`
- `business`
type: array
items:
type: string
holder_types:
description: |
The Holder Type values supplied in the request to generate the given result set.
Currently supported values include (but are not necessarily limited to):
- `sole`
- `joint`
- `delegate`
- `unknown`
type: array
items:
type: string
providers:
description: The Provider values supplied in the request to generate the given result set.
type: array
items:
type: string
result_count:
type: number
description: The number of accounts returned in the results
RetrieveAccountByIDV2Response:
title: Retrieve Account By ID Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- financial_v2_accounts_account_id
data:
$ref: '#/components/schemas/AccountV2'
metadata:
type: object
BalanceAmount:
title: Balance amount
description: A representation of both the amount and the credit/debit indicator
required:
- amount
- type
- credit_debit_indicator
properties:
amount:
$ref: '#/components/schemas/BudAmount'
type:
type: string
description: |
The type for the given balance.
Currently supported values include (but are not necessarily limited to):
- `closing_available`
- `closing_booked`
- `closing_cleared`
- `expected`
- `forward_available`
- `information`
- `interim_available`
- `interim_booked`
- `interim_cleared`
- `opening_available`
- `opening_booked`
- `opening_cleared`
- `previously_closed_booked`
credit_debit_indicator:
type: string
description: Indication as to whether the balance is in credit or debit
enum:
- credit
- debit
BalanceOverTimeDataPoint:
title: Balance Over Time Data-Point
description: A single record of the balance at the end of the given date.
type: object
required:
- date
- booked
properties:
date:
type: string
description: |
The date of the given balance in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-03-17T23:59:59Z`
- `2023-03-17T23:59:59-08:00`
booked:
description: The current balance of the account
$ref: '#/components/schemas/BalanceAmount'
pending:
description: The balance of the account if all pending transactions have settled. This field is only present if the pending balance is different than the booked balance.
$ref: '#/components/schemas/BalanceAmount'
GetBalancesResponse:
title: Get Balances Response
type: object
required:
- operation_id
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
type: object
required:
- balances
properties:
account_id:
type: string
description: Identifier of the accounts from which the balances have been calculated
balances:
type: array
items:
$ref: '#/components/schemas/BalanceOverTimeDataPoint'
metadata:
type: object
properties:
accounts:
description: This is a hashmap representing account_ids and metadata about the results returned from the balances endpoint
additionalProperties:
description: Hashmap of an account_id returned from the balances endpoint
allOf:
- $ref: '#/components/schemas/BudDateRangeMetadata'
- type: object
properties:
balance_count:
type: number
description: The number of balances returned for the account
- type: object
properties:
min_balance:
description: The minimum balance in the returned period
$ref: '#/components/schemas/BudAmount'
- type: object
properties:
max_balance:
description: The maximum balance in the returned period
$ref: '#/components/schemas/BudAmount'
parameters:
title: The parameters used to calculated balances
allOf:
- $ref: '#/components/schemas/BudDateRangeMetadata'
- type: object
properties:
granularity:
type: string
description: |
The granularity that the balances have been retrieved for.
Currently supported values include (but are not necessarily limited to):
- `daily`
- `weekly`
- `biweekly`
- `monthly`
- `quarterly`
- `six_monthly`
- `annually`
GetBalancesForAccountIDResponse:
title: Get Balances For Account ID Response
type: object
required:
- operation_id
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
$ref: '#/components/schemas/BalanceOverTimeDataPoint'
metadata:
type: object
properties:
accounts:
description: Metadata about the response for the given account_id
allOf:
- $ref: '#/components/schemas/BudDateRangeMetadata'
- type: object
properties:
balance_count:
type: number
description: The number of balances returned for the account
- type: object
properties:
min_balance:
description: The minimum balance in the returned period
$ref: '#/components/schemas/BudAmount'
- type: object
properties:
max_balance:
description: The maximum balance in the returned period
$ref: '#/components/schemas/BudAmount'
parameters:
allOf:
- $ref: '#/components/schemas/BudDateRangeMetadata'
- type: object
properties:
granularity:
type: string
description: The granularity that the balances have been retrieved for.
account_id:
type: string
description: The account ID the balances have been retrieved for.
CustomerCategoryCorrectionPayload:
title: Customer Category Correction
type: object
description: Expected request structure for the category corrections endpoint
required:
- transaction_id
properties:
transaction_id:
type: string
description: The unique identifier for the transaction
category_l1:
type: string
description: The name of the category that the transaction should be assigned
category_l2:
type: string
description: The name of the subcategory that the transaction should be assigned
include_similar:
type: boolean
description: Correct the category of other similar transactions to the specified transaction
default: false
CustomerCategoryCorrectionRequest:
title: Customer Category Corrections Request Payload
type: array
description: Expected request structure for the category corrections endpoint
items:
$ref: '#/components/schemas/CustomerCategoryCorrectionPayload'
CategoryCorrectionResponseMetadata:
title: Results Metadata Object
type: object
description: Metadata associated with the response schema
properties:
results:
type: number
description: The number of category correction rules created
CustomerCategoryCorrectionResponse:
title: Customer Category Corrections Response
type: object
description: Expected response structure for the category corrections endpoint
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
$ref: '#/components/schemas/CustomerCategoryCorrectionPayload'
metadata:
$ref: '#/components/schemas/CategoryCorrectionResponseMetadata'
CustomerMerchantCorrectionPayload:
title: Customer Merchant Correction
type: object
description: Expected request structure for the merchant corrections endpoint
required:
- transactions
properties:
transactions:
type: array
minItems: 1
items:
type: string
description: A list of transaction identifiers to be corrected
merchant_id:
type: string
description: |
The identifier of the merchant that the transactions should be assigned
To remove a merchant instead of replacing it, leave this value blank
include_similar:
type: boolean
description: Correct the merchant of other similar transactions to the specified transactions
default: false
CustomerMerchantCorrectionRequest:
title: Customer Merchant Corrections Request Payload
type: array
description: Expected request structure for the merchant corrections endpoint
items:
$ref: '#/components/schemas/CustomerMerchantCorrectionPayload'
CustomerMerchantCorrectionSearchResult:
type: object
required:
- id
- display_name
- slug
- logo
properties:
id:
type: string
format: uuid
description: UUID corresponding to the merchant, if available. Subject to version control.
display_name:
type: string
description: UI friendly display name for the merchant.
slug:
type: string
description: Unique human readable identifier of the merchant. Not subject to version control.
logo:
type: string
description: A url to the merchant logo. If not available a placeholder is used
website:
type: string
description: URL supplying merchant website, if available.
CustomerMerchantCorrectionSearchResponsePayload:
title: Customer Merchant Corrections Request Payload
type: array
description: List of merchant that matched the query. Best match first
items:
$ref: '#/components/schemas/CustomerMerchantCorrectionSearchResult'
CustomerMerchantCorrectionSearchResponseMetadata:
title: Customer Merchant Corrections Search Response Metadata
type: object
required:
- query
- results
properties:
query:
type: string
description: Query used in the request
results:
type: number
description: Number of results returned
CustomerMerchantCorrectionSearchResponse:
title: Customer Merchant Correction Search Response
type: object
description: Expected response structure for the merchant corrections search endpoint
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/CustomerMerchantCorrectionSearchResponsePayload'
metadata:
$ref: '#/components/schemas/CustomerMerchantCorrectionSearchResponseMetadata'
CustomMerchant:
title: Custom Merchant
description: Custom Merchant Object
type: object
required:
- custom_merchant_id
- name
- suggested_url
- online_or_billing_only
- created_at
properties:
custom_merchant_id:
format: uuid
type: string
description: UUID representing the custom merchant.
name:
type: string
description: Provided name for the custom merchant.
suggested_url:
type: string
description: Provided URL for the custom merchant
online_or_billing_only:
type: boolean
description: Provided online or billing only identifier for the custom merchant.
created_at:
type: string
description: Date that the custom merchant was created, compliant with RFC3339.
CustomMerchantRequest:
title: Custom Merchant Request
type: object
required:
- name
properties:
name:
type: string
description: The display name of the custom merchant to be created
example: Krystian Wines
suggested_url:
type: string
description: A suggested URL for the merchant, to help bud identify it and expand our merchant database.
example: https://www.example.com
online_or_billing_only:
type: boolean
description: This is used to indicate if the custom merchant being created is an exclusively online or billing merchant.
example: false
MerchantFeedbackRequest:
title: Merchant Feedback Request
type: object
required:
- logo_feedback
properties:
logo_feedback:
type: string
description: The type of feedback for the merchant.
enum:
- missing_logo
- wrong_logo
- low_quality_logo
- out_of_date_logo
suggested_logo:
type: string
suggested_url:
type: string
MerchantFeedbackResponse:
title: Merchant Feedback Response
type: object
required:
- merchant_id
- logo_feedback
properties:
merchant_id:
type: string
description: The merchant the feedback has been created for.
logo_feedback:
type: string
description: The type of feedback for the merchant.
enum:
- missing_logo
- wrong_logo
- low_quality_logo
- out_of_date_logo
suggested_logo:
type: string
suggested_url:
type: string
BaseSpendingBudget:
title: Spending Budget
type: object
required:
- name
- amount
- recurrency
properties:
name:
title: Name
type: string
description: |
The name of the spending budget.
Example: `Travel`
example: Travel
amount:
title: Amount
type: object
description: |
The amount of money to be budgeted for. Must be greater than 0.
required:
- value
- currency
properties:
value:
$ref: '#/components/schemas/BudMonetaryValue'
currency:
$ref: '#/components/schemas/BudCurrency'
recurrency:
title: Recurrency
type: object
description: |
Whether and/or how often the budget recurs.
The `starting_day` is only required for budgets with a recurring period e.g. `monthly`
New periods may be added without a breaking change notice.
required:
- period
properties:
period:
title: Period
type: string
description: |
The period at which a budget recurs (if at all).
Currently supported options are:
- `one-off`
- `monthly`
New periods may be added without a breaking change notice.
starting_day:
title: Starting Day
type: integer
description: |
The day of which the budget period starts. Not required if a budget is `one-off`.
Must be between 1 and 28 for `monthly` budgets.
include:
title: Include
type: object
description: |
The inclusion criteria for transactions to be included in the budget.
properties:
categories:
title: Categories
description: |
The categories of transactions to be included in the budget.
If L2 categories are specified, they must be grouped underneath their corresponding L1 category.
All categories specified must be compatible with the category taxonomy used for that customer.
type: array
items:
required:
- l1
properties:
l1:
title: L1
type: string
description: |
L1 category to include in the filter. Must be specified if using category filtering.
l2:
title: L2
type: array
description: |
L2 categories to include in the filter. Must all correspond to the parent L1 category specified.
items:
type: string
merchants:
title: Merchants
type: object
description: |
The merchants of transactions to be included in the budget.
properties:
slugs:
title: Slugs
type: array
description: |
The slugs of merchants to be included. E.g. `netflix` or `uber`
items:
type: string
SpendingBudget:
allOf:
- $ref: '#/components/schemas/BaseSpendingBudget'
- type: object
required:
- id
- name
- amount
- recurrency
- spent
- created_at
properties:
id:
title: ID
type: string
description: |
The ID of the spending budget.
Example: "81a68821-dca6-4771-80d4-002c7fce412e"
spent:
title: Spent
type: object
description: |
The amount of money spent from the budget for the given time period.
required:
- from
- to
- amount
- ratio
properties:
from:
title: From
type: string
description: |
The date from which the budgeting period began in the format [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt).
Example: `2023-10-01T00:00:00Z`
to:
title: From
type: string
description: |
The date to which the budgeting period ends in the format [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt).
Example: `2023-10-31T00:00:00Z`
amount:
title: Amount
type: object
description: |
The amount of money spent from the budget.
required:
- value
- currency
properties:
value:
$ref: '#/components/schemas/BudMonetaryValue'
currency:
$ref: '#/components/schemas/BudCurrency'
ratio:
title: Ratio
type: string
description: |
The ratio of spent money to the total budget amount.
created_at:
title: Created At
type: string
description: |
The date and time the budget was created in the format [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt).
Example: `2023-10-17T00:00:00Z`
_links:
title: _links
type: object
description: |
Useful follow up links
properties:
transactions:
title: Transactions Link
type: string
description: |
Link to follow to get transactions included in the budget.
BudResultsMetadata:
title: Metadata
type: object
required:
- results
properties:
results:
type: integer
description: |
The number of results returned in the response.
Example: 1
example: 1
RetrieveSpendingBudgetsResponse:
title: Retrieve Spending Budgets Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
title: Operation ID
type: string
enum:
- goals_v1_spending_budgets_get
data:
type: array
items:
$ref: '#/components/schemas/SpendingBudget'
metadata:
allOf:
- $ref: '#/components/schemas/BudResultsMetadata'
- type: object
properties:
account_ids:
title: Account IDs
type: array
description: |
An array of account IDs used for filtering in the request.
items:
type: string
description: |
An account ID used for filtering in the request.
Example: `RxsYshVGded4JeilkXgWKdXA`
CreateSpendingBudgetRequest:
title: Create Spending Budget Request
allOf:
- $ref: '#/components/schemas/BaseSpendingBudget'
CreateSpendingBudgetResponse:
title: Create Spending Budget Response
type: object
required:
- operation_id
- data
properties:
operation_id:
title: Operation ID
type: string
enum:
- goals_v1_spending_budgets_post
data:
$ref: '#/components/schemas/SpendingBudget'
PatchSpendingBudget:
title: Patch Spending Budget
type: object
properties:
name:
title: Name
type: string
description: |
The name of the spending budget.
Example: `Travel`
example: Travel
amount:
title: Amount
type: object
description: |
The amount of money to be budgeted for. Must be greater than 0.
Note: The Currency of a spending budget cannot be updated.
required:
- value
properties:
value:
$ref: '#/components/schemas/BudMonetaryValue'
recurrency:
title: Recurrency
type: object
description: |
Whether and/or how often the budget recurs.
The `starting_day` is only required for budgets with a recurring period e.g. `monthly`
New periods may be added without a breaking change notice.
required:
- period
properties:
period:
title: Period
type: string
description: |
The period at which a budget recurs (if at all).
Currently supported options are:
- `one-off`
- `monthly`
New periods may be added without a breaking change notice.
starting_day:
title: Starting Day
type: integer
description: |
The day of which the budget period starts. Not required if a budget is `one-off`.
Must be between 1 and 28 for `monthly` budgets.
include:
title: Include
type: object
description: |
The inclusion criteria for transactions to be included in the budget.
properties:
categories:
title: Categories
description: |
The categories of transactions to be included in the budget.
If L2 categories are specified, they must be grouped underneath their corresponding L1 category.
All categories specified must be compatible with the category taxonomy used for that customer.
type: array
items:
required:
- l1
properties:
l1:
title: L1
type: string
description: |
L1 category to include in the filter. Must be specified if using category filtering.
l2:
title: L2
type: array
description: |
L2 categories to include in the filter. Must all correspond to the parent L1 category specified.
items:
type: string
merchants:
title: Merchants
type: object
description: |
The merchants of transactions to be included in the budget.
properties:
slugs:
title: Slugs
type: array
description: |
The slugs of merchants to be included. E.g. `netflix` or `uber`
items:
type: string
UpdateSpendingBudgetResponse:
title: Update Spending Budget Response
type: object
required:
- operation_id
- data
properties:
operation_id:
title: Operation ID
type: string
enum:
- goals_v1_spending_budgets_patch
data:
$ref: '#/components/schemas/SpendingBudget'
schemas-Categories:
title: Categories
type: object
description: |
Categories enrichment associated with a Transaction, as generated by Bud's artificial intelligence models.
Currently two levels of category are supported, with `l1` being a coarse-grained category level and `l2` being
more refined.
required:
- l1
- l2
properties:
l1:
$ref: '#/components/schemas/Category'
description: Level 1 Category
l2:
$ref: '#/components/schemas/Category'
description: Level 2 Category
goals-components_schemas-Merchant:
title: Merchant
type: object
description: |
Merchant enrichment associated with a Transaction, as generated using a combination of Bud's artificial
intelligence models and database of known merchants.
required:
- id
- slug
- display_name
properties:
id:
type: string
description: UUID corresponding to the merchant, if available. Subject to version control.
slug:
type: string
description: Unique human readable identifier of the merchant. Not subject to version control.
display_name:
type: string
description: UI friendly display name for the merchant.
logo:
type: string
description: URL supplying merchant logo, if available.
schemas-Enrichments:
title: Enrichments
type: object
description: Contextual enrichments associated with a Transaction
properties:
categories:
$ref: '#/components/schemas/schemas-Categories'
merchant:
$ref: '#/components/schemas/goals-components_schemas-Merchant'
schemas-Transaction:
title: Transaction
type: object
description: A financial transaction
required:
- transaction_id
- account_id
- description
- amount
- credit_debit_indicator
- suggested_description
- status
- date_time
properties:
transaction_id:
type: string
description: Unique identifier for the transaction. May be mutable depending on original ingestion source.
account_id:
type: string
description: Identifier for the account associated with the transaction.
provider:
type: string
description: Name of the transaction source provider. Optional as it may not have been supplied when using first party data.
description:
type: string
description: Description of the transaction.
credit_debit_indicator:
type: string
description: Credit/Debit Indicator
enum:
- credit
- debit
status:
type: string
description: Status of the transaction. Defaults to booked.
enum:
- booked
- pending
amount:
$ref: '#/components/schemas/BudAmount'
date_time:
type: string
description: Date of the transaction compliant with RFC3339.
enrichments:
$ref: '#/components/schemas/schemas-Enrichments'
suggested_description:
description: The description Bud suggests client apps show for a given transaction.
type: string
suggested_logo:
description: The logo Bud suggests client apps show for a given transaction.
type: string
format: uri
BudPageSizeMetadata:
title: Page Size
type: integer
description: |
The size of the page requested.
Example: `100`
example: 100
BudNextPageTokenMetadata:
title: Next Page Token
type: object
properties:
next_page_token:
type: string
description: |
The token to use to fetch the next page of results. This is only set if there are more results to fetch.
example:
next_page_token: b21055a9a9f46fc794a2e6855c65abd7e317181039fc6930daabac5822911d14a84895ecd947e2b5abdcb22e4fcc2c594e1f661dc63e34b9ba88760724047990896f7581a0786c2605dce19c6a9d80d1044f963b74fea0a929c0a4465a6e67378a74dce38ec5e26ae4cc804b62fd666d5df4cf2e7f524bd99e5523bc5d471768065c036dc0c73122705b280817fbbd7d9aa31f271d72cd3877d999dcb9a5b1c0be0c05
RetrieveSpendingBudgetTransactionsResponse:
title: Retrieve Spending Budget Transactions Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
title: Operation ID
type: string
enum:
- goals_v1_spending_budget_transactions_get
data:
type: array
items:
$ref: '#/components/schemas/schemas-Transaction'
metadata:
allOf:
- $ref: '#/components/schemas/BudResultsMetadata'
- type: object
properties:
budget_id:
title: Budget ID
type: string
description: |
The ID of the spending budget the transactions were retrieved for.
Example: "81a68821-dca6-4771-80d4-002c7fce412e"
example: 81a68821-dca6-4771-80d4-002c7fce412e
page_size:
$ref: '#/components/schemas/BudPageSizeMetadata'
- $ref: '#/components/schemas/BudNextPageTokenMetadata'
CreateSavingsGoalV2Request:
title: Create Savings Goal V2 Request
required:
- account_id
- name
- target_amount
- allocation_ratio
properties:
account_id:
title: Account ID
type: string
description: |
The account ID the savings goal is associated with.
Example: `RxsYshVGded4JeilkXgWKdXA`
example: RxsYshVGded4JeilkXgWKdXA
name:
title: Name
type: string
description: |
The name of the savings goal.
Example: `Holiday`
example: Holiday
target_amount:
title: Target Amount
type: object
description: |
The target amount of money to be saved for this goal.
required:
- value
- currency
properties:
value:
$ref: '#/components/schemas/BudMonetaryValue'
currency:
$ref: '#/components/schemas/BudCurrency'
target_datetime:
title: Target Datetime
type: string
description: |
The optional target date by which the savings goal should be reached, in the format [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339). Must be a future date.
Examples:
- `2025-12-31T00:00:00Z`
- `2025-12-31T00:00:00+01:00`
allocation_ratio:
title: Allocation Ratio
type: number
format: float
description: |
The proportion of the account balance to allocate to this savings goal. Must be greater than `0` and at most `1`.
Example: `0.2`
example: 0.2
SavingsGoalV2:
title: Savings Goal V2
required:
- id
- account_id
- name
- target_amount
- allocation_ratio
- goal_balance
- created_at
properties:
id:
title: ID
type: string
format: uuid
description: |
The ID of the savings goal.
Example: `81a68821-dca6-4771-80d4-002c7fce412e`
example: 81a68821-dca6-4771-80d4-002c7fce412e
account_id:
title: Account ID
type: string
description: |
The account ID the savings goal is associated with.
Example: `RxsYshVGded4JeilkXgWKdXA`
example: RxsYshVGded4JeilkXgWKdXA
name:
title: Name
type: string
description: |
The name of the savings goal.
Example: `Holiday`
example: Holiday
target_amount:
title: Target Amount
type: object
description: |
The target amount of money to be saved for this goal.
required:
- value
- currency
properties:
value:
$ref: '#/components/schemas/BudMonetaryValue'
currency:
$ref: '#/components/schemas/BudCurrency'
target_datetime:
title: Target Datetime
type: string
description: |
The optional target date by which the savings goal should be reached, in the format [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2025-12-31T00:00:00Z`
- `2025-12-31T00:00:00+01:00`
allocation_ratio:
title: Allocation Ratio
type: number
format: float
description: |
The proportion of the account balance allocated to this savings goal. Must be greater than `0` and at most `1`.
For example, a value of `0.2` means 20% of the account balance is considered allocated to this goal.
Example: `0.2`
example: 0.2
goal_balance:
title: Goal Balance
type: object
description: |
The current balance allocated to this savings goal, calculated as the account balance multiplied by the `allocation_ratio`.
required:
- value
- currency
properties:
value:
$ref: '#/components/schemas/BudMonetaryValue'
currency:
$ref: '#/components/schemas/BudCurrency'
created_at:
title: Created At
type: string
description: |
The date and time the savings goal was created in the format [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
CreateSavingsGoalV2Response:
title: Create Savings Goal V2 Response
required:
- operation_id
- data
properties:
operation_id:
title: Operation ID
type: string
enum:
- goals_v2_savings_goal_post
data:
$ref: '#/components/schemas/SavingsGoalV2'
RetrieveSavingsGoalsV2Response:
title: Retrieve Savings Goals V2 Response
required:
- operation_id
- data
properties:
operation_id:
title: Operation ID
type: string
enum:
- goals_v2_savings_goals_get
data:
type: array
items:
$ref: '#/components/schemas/SavingsGoalV2'
RetrieveSavingsGoalV2Response:
title: Retrieve Savings Goal V2 Response
required:
- operation_id
- data
properties:
operation_id:
title: Operation ID
type: string
enum:
- goals_v2_savings_goal_get
data:
$ref: '#/components/schemas/SavingsGoalV2'
UpdateSavingsGoalV2Request:
title: Update Savings Goal V2 Request
properties:
account_id:
title: Account ID
type: string
description: |
The account ID the savings goal is associated with.
Example: `RxsYshVGded4JeilkXgWKdXA`
example: RxsYshVGded4JeilkXgWKdXA
name:
title: Name
type: string
description: |
The name of the savings goal.
Example: `Holiday`
example: Holiday
target_amount:
title: Target Amount
type: object
description: |
The target amount of money to be saved for this goal.
required:
- value
- currency
properties:
value:
$ref: '#/components/schemas/BudMonetaryValue'
currency:
$ref: '#/components/schemas/BudCurrency'
target_datetime:
title: Target Datetime
type: string
nullable: true
description: |
The target date by which the savings goal should be reached, in the format [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339). Must be a future date. Set to `null` to remove the target date.
Examples:
- `2025-12-31T00:00:00Z`
- `2025-12-31T00:00:00+01:00`
allocation_ratio:
title: Allocation Ratio
type: number
format: float
description: |
The proportion of the account balance to allocate to this savings goal. Must be greater than `0` and at most `1`.
Example: `0.25`
example: 0.25
UpdateSavingsGoalV2Response:
title: Update Savings Goal V2 Response
required:
- operation_id
- data
properties:
operation_id:
title: Operation ID
type: string
enum:
- goals_v2_savings_goal_patch
data:
$ref: '#/components/schemas/SavingsGoalV2'
RegularPaymentsConfirmed:
title: Regular Payment Object
type: object
description: Details surrounding the regularity of the transaction
required:
- label
- period
- score
properties:
label:
type: string
description: A recurring transaction group identifier label associating regular transactions e.g. all Spotify transactions that are regular by the same monthly period will share the same label. The format of the label includes a hash of the transaction description and the amount, followed by an integer corresponding to the number of regular groups found, i.e. -.
period:
type: string
description: To describe the period between each transaction in a regular group.
enum:
- daily
- weekly
- biweekly
- monthly
- quarterly
- unknown
score:
type: string
description: A floating point number between 0 and 1, to define the confidence level that the transaction is regular or not.
LegacyBudAmount:
title: Legacy Bud Amount
type: object
description: The monetary amount.
required:
- amount
- currency
properties:
amount:
$ref: '#/components/schemas/BudMonetaryValue'
currency:
$ref: '#/components/schemas/BudCurrency'
NullableMerchant:
title: Bud Merchant Object
type: object
nullable: true
description: Details regarding a merchant associated with a transaction
required:
- id
- name
- logo
properties:
id:
type: string
description: Identifier for the detected merchant
name:
type: string
description: Display name for the detected merchant
logo:
type: string
description: URL for logo of the detected merchant
BasicTransactionWithNullableMerchant:
title: Basic Transaction With Nullable Merchant Schema
type: object
description: Basic transaction with nullable merchant schema
required:
- transaction_id
- account_id
- transaction_description
- provider
- date
- amount
- credit_debit_indicator
properties:
transaction_id:
type: string
description: A unique identifier for the transaction
account_id:
type: string
description: A unique identifier for the Customer bank account
transaction_description:
type: string
description: Any Customer defined input, e.g. a bank transfer reference
provider:
type: string
description: The name of the relevant provider relevant to the source of the original transaction data
date:
type: string
description: The date (YYYY-MM-DD) that the transaction took place
amount:
$ref: '#/components/schemas/LegacyBudAmount'
credit_debit_indicator:
type: string
description: Indication as to whether the transaction was a credit or debit
enum:
- Credit
- Debit
merchant:
$ref: '#/components/schemas/NullableMerchant'
RegularTransaction:
title: Regular Transaction Group
description: Information surrounding a possible group of Regular transactions
allOf:
- $ref: '#/components/schemas/RegularPaymentsConfirmed'
- type: object
required:
- transactions
properties:
transactions:
type: array
items:
$ref: '#/components/schemas/BasicTransactionWithNullableMerchant'
RegularTransactionsResponse:
title: Regular Transactions (Aggregated) Response
type: object
description: Regular Transactions from Aggregated Data Response
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
description: Information surrounding possible groups of Regular transactions
items:
$ref: '#/components/schemas/RegularTransaction'
metadata:
$ref: '#/components/schemas/ResultsMetadata'
FutureTransactionV2:
allOf:
- type: object
description: Expected transaction structure
required:
- transaction_id
- account_id
- transaction_description
- date_time
- amount
- credit_debit_indicator
- label
- period
- confidence
- future_transactions
properties:
transaction_id:
type: string
description: Unique identifier for the transaction.
account_id:
type: string
description: Unique identifier for the account.
transaction_description:
type: string
description: Further details of the transaction. This is the transaction narrative, which is unstructured text.
date_time:
type: string
description: The date of the transaction. In the following format RFC-3339 'Year-Month-Day Hour:Minute:Second'. E.g '2019-07-01T01:00:00'
amount:
$ref: '#/components/schemas/BudAmount'
credit_debit_indicator:
type: string
description: Indication as to whether the transaction was a credit or debit. If credit then debtor is required. If debit then creditor required.
enum:
- credit
- debit
label:
type: string
description: Unique identifier for the regular transaction group
period:
type: string
description: To describe the frequency of each transaction
enum:
- daily
- weekly
- biweekly
- monthly
- quarterly
- unknown
confidence:
type: string
description: Probability score
categories:
type: object
description: Categories of the original transaction
properties:
l1:
type: object
description: Level 1 Category
properties:
slug:
type: string
description: Unique human readable identifier of the category
confidence:
type: string
description: Degree of belief of correct assignment, expressed as a probability
l2:
type: object
description: Level 2 Category
properties:
slug:
type: string
description: Unique human readable identifier of the category
confidence:
type: string
description: Degree of belief of correct assignment, expressed as a probability
future_transactions:
type: array
items:
type: object
description: Dates and amounts of the predicted future occurrences
required:
- date
properties:
date:
type: string
description: The next date at which the future transaction will occur in the following format, 'Year-Month-Day'. E.g '2019-07-01'
amount:
type: object
$ref: '#/components/schemas/BudAmount'
FutureTransactionV2Response:
allOf:
- type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
$ref: '#/components/schemas/FutureTransactionV2'
metadata:
type: object
required:
- results
- months
properties:
results:
type: number
description: The number of different upcoming transactions that have been found
months:
type: number
description: The number of months for which the upcoming transactions have been projected
change_percentages:
type: array
description: A list of all of the percentage value changes that have been applied to different Level 2 categories
items:
type: object
required:
- l2
- value
properties:
l2:
type: string
description: The l2 category that a percentage change has been applied to
example: bills
value:
type: number
description: The percentage of change that has been applied to the given l2 category
example: 2
BasicTransactionV2:
title: Basic Transaction Schema
type: object
description: Basic transaction schema
required:
- transaction_id
- account_id
- transaction_description
- provider
- date
- amount
- credit_debit_indicator
properties:
transaction_id:
type: string
description: A unique identifier for the transaction
account_id:
type: string
description: A unique identifier for the Customer bank account
transaction_description:
type: string
description: A description of the transaction, similar to the transaction information in Open Banking. e.g. a bank transfer reference"
provider:
type: string
description: The name of the relevant provider relevant to the source of the original transaction data
date:
type: string
description: |
The date of the transaction in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-03-17T17:29:51Z`
- `2023-03-17T17:29:51-08:00`
amount:
$ref: '#/components/schemas/BudAmount'
credit_debit_indicator:
type: string
description: Indication as to whether the transaction was a credit or debit
enum:
- Credit
- Debit
CategoriserCategory:
title: Categoriser Category
type: object
description: The details in relation to a specific category level, as taken from the output of Bud's categorsiation service.
required:
- name
- confidence
- label
properties:
name:
type: string
description: Internal name (identifier) of the category
confidence:
type: string
description: The level of certainty that the model has predicted the category
label:
type: string
description: Humanised category name
MerchantIdV2:
title: Merchant ID Object
type: object
description: Details surrounding the identified merchant of the transaction
required:
- id
- name
- logo
- confidence
properties:
id:
type: string
description: A unique ID for the identified merchant
name:
type: string
description: The clean name of the identified merchant
logo:
type: string
description: The merchant's logo image URL location
confidence:
type: string
description: The level of certainty that the model has predicted the merchant
ProcessorIdV2:
title: Processor ID Object
type: object
description: Details surrounding the identified processor of the transaction
required:
- id
- name
- logo
- confidence
properties:
id:
type: string
description: A unique ID for the identified processor
name:
type: string
description: The clean name of the identified processor
logo:
type: string
description: The processor's logo image URL location
confidence:
type: string
description: The level of certainty that the model has predicted the processor
IncomeEnrichmentV2:
title: Income Enrichment
type: object
description: Results from Bud's Income Finder Service
required:
- type
- confidence
properties:
type:
type: string
description: The type of identified income type, either `salary_or_wages` or `other_incoming`
confidence:
type: string
description: The level of certainty that the model has predicted an income related transaction.
IncomeEnrichmentsV2:
type: object
title: Income Transaction Enrichments
description: Results from required enrichment services for successful marking of income transactions
properties:
categories:
type: object
nullable: true
title: Categoriser_Enrichment
description: Results from Bud's Categorisation Service
required:
- l1
- l2
- l3
properties:
l1:
type: array
description: Details on the Level One category associated with the transaction
items:
$ref: '#/components/schemas/CategoriserCategory'
l2:
type: array
description: Details on the Level Two category associated with the transaction
items:
$ref: '#/components/schemas/CategoriserCategory'
l3:
type: array
description: Details on the Level Three category associated with the transaction
items:
$ref: '#/components/schemas/CategoriserCategory'
merchant:
allOf:
- type: object
nullable: true
- $ref: '#/components/schemas/MerchantIdV2'
processor:
allOf:
- type: object
nullable: true
- $ref: '#/components/schemas/ProcessorIdV2'
income:
allOf:
- type: object
nullable: true
- $ref: '#/components/schemas/IncomeEnrichmentV2'
IncomeTransactionV2:
allOf:
- $ref: '#/components/schemas/BasicTransactionV2'
- title: Income Transaction
required:
- enrichment
properties:
enrichment:
$ref: '#/components/schemas/IncomeEnrichmentsV2'
IncomeAverageOverPeriod:
title: Average income statistics over time period
type: object
required:
- income
- regular_income
properties:
income:
allOf:
- description: average of all income transactions
- $ref: '#/components/schemas/BudAmount'
regular_income:
allOf:
- description: average income transactions that we have also detected as regular
- $ref: '#/components/schemas/BudAmount'
IncomeAverage:
title: Average income statistics
type: object
description: |-
Averages of income amounts. These averages are calculated using the filters supplied in the `X-From` & `X-To` headers.
For instance, with 6 months of £1000/month and a date range of 6 months, the monthly average will be £1000.
However, if the supplied date range is 12 months and there is no data for more than those 6 months, the average will be £500/month.
Note that the number of months are calculated inclusively e.g. `months(2022-01-01, 2022-02-28) = 2` and `months(2022-01-01, 2022-03-01) = 3`.
required:
- monthly
properties:
monthly:
allOf:
- description: average income per month
- $ref: '#/components/schemas/IncomeAverageOverPeriod'
IncomeStatistics:
type: object
title: Income statistics
required:
- average
properties:
average:
$ref: '#/components/schemas/IncomeAverage'
IncomeResponseV2:
type: object
title: Income Finder Response V2
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
title: Income_Finder_Response_Data
required:
- transactions
- statistics
properties:
transactions:
type: array
title: Income Transactions
items:
$ref: '#/components/schemas/IncomeTransactionV2'
statistics:
$ref: '#/components/schemas/IncomeStatistics'
metadata:
$ref: '#/components/schemas/TransactionsResultsMetadata'
BasicTransaction:
title: Basic Transaction Schema
type: object
description: Basic transaction schema
required:
- transaction_id
- account_id
- transaction_description
- provider
- date
- amount
- credit_debit_indicator
properties:
transaction_id:
type: string
description: A unique identifier for the transaction
account_id:
type: string
description: A unique identifier for the Customer bank account
transaction_description:
type: string
description: Any Customer defined input, e.g. a bank transfer reference
provider:
type: string
description: The name of the relevant provider relevant to the source of the original transaction data
date:
type: string
description: |
The date of the transaction in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-03-17T17:29:51Z`
- `2023-03-17T17:29:51-08:00`
amount:
$ref: '#/components/schemas/LegacyBudAmount'
credit_debit_indicator:
type: string
description: Indication as to whether the transaction was a credit or debit
enum:
- Credit
- Debit
Benefit:
title: Benefit
type: object
required:
- type
- display_name
properties:
type:
type: string
description: The type of benefit
example: attendance_allowance
display_name:
type: string
example: Attendance Allowance
description: The display name of the benefit type
BenefitsTransactionV1:
title: Benefit Transactions
allOf:
- $ref: '#/components/schemas/BasicTransaction'
- type: object
required:
- benefit
properties:
benefit:
$ref: '#/components/schemas/Benefit'
BenefitsResponseV1:
title: Benefits Finder Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
description: Array of Benefits related transactions
items:
$ref: '#/components/schemas/BenefitsTransactionV1'
metadata:
$ref: '#/components/schemas/TransactionsResultsMetadata'
BenefitsTotalsResponseV1:
title: Benefit Totals
type: object
description: Benefits Total income structure
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
type: object
required:
- benefit
- total_credit
properties:
benefit:
$ref: '#/components/schemas/Benefit'
total_credit:
$ref: '#/components/schemas/BudAmount'
metadata:
$ref: '#/components/schemas/TransactionsResultsMetadata'
LoanTransactionV1:
title: Loan Transaction
allOf:
- $ref: '#/components/schemas/BasicTransactionV2'
- type: object
properties:
merchant:
allOf:
- type: object
nullable: true
- $ref: '#/components/schemas/MerchantIdV2'
LoanStatistics:
type: object
title: Loan Statistics
required:
- total_debit
properties:
total_debit:
allOf:
- description: Total debit amount of all loan transactions
- $ref: '#/components/schemas/BudAmount'
LoansResponseV1:
title: Loans Finder Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
title: Loan_Finder_Response_Data
required:
- transactions
- statistics
properties:
transactions:
type: array
title: Loan Transactions
items:
$ref: '#/components/schemas/LoanTransactionV1'
statistics:
$ref: '#/components/schemas/LoanStatistics'
metadata:
$ref: '#/components/schemas/TransactionsResultsMetadata'
DebtCollectionTransaction:
allOf:
- $ref: '#/components/schemas/BasicTransactionV2'
- type: object
title: Debt Collection Transaction
required:
- merchant
properties:
merchant:
$ref: '#/components/schemas/MerchantIdV2'
IncomeRelationStatistics:
type: object
title: Income Relations
description: Comparisons of the returned transactions to the income found over the same period
required:
- expense_to_income_ratio
- total_income
properties:
expense_to_income_ratio:
description: The ratio of total debit amounts of the returned transactions to the total income over the same period, to 3 decimal places.
type: string
total_income:
allOf:
- description: Total income over the provided period
- $ref: '#/components/schemas/BudAmount'
DebtCollectionStatistics:
type: object
title: Debt Collection Statistics
required:
- total_debit
- income_relations
properties:
total_debit:
allOf:
- description: Total debit amount of all debt collection transactions
- $ref: '#/components/schemas/BudAmount'
income_relations:
$ref: '#/components/schemas/IncomeRelationStatistics'
DebtCollectionResponseV1:
type: object
title: Debt Collection Finder Response
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
title: Debt_Collection_Finder_Response_Data
required:
- transactions
- statistics
properties:
transactions:
type: array
title: Debt Collection Transactions
items:
$ref: '#/components/schemas/DebtCollectionTransaction'
statistics:
$ref: '#/components/schemas/DebtCollectionStatistics'
metadata:
$ref: '#/components/schemas/TransactionsResultsMetadata'
GetProductsResponseV2:
title: Retrieve Financial Products V2 Response Structure
type: object
required:
- operation_id
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: array
items:
title: Financial_Product
description: A Financial Product that a customer uses.
type: object
required:
- type
- merchant
- amount
- period
properties:
type:
title: Financial_Product_Type
description: |
A list of the types products and services identified for the given Financial Product. Potential values could be (but not limited to):
- `loan`
- `bnpl`
- `mortgage`
- `insurance`
- `credit_card`
- `private_pension`
- `savings_and_investment`
type: array
items:
type: string
merchant:
title: Financial_Product_Merchant
description: Details of the merchant providing the Financial Product.
type: object
required:
- id
- name
- logo
properties:
id:
type: string
description: A unique ID for the merchant.
name:
type: string
description: The merchant's name in a displayable format.
logo:
type: string
description: The merchant's logo image URL location.
amount:
$ref: '#/components/schemas/BudAmount'
period:
title: Transaction Period
description: |
The period between each transaction for the given product. Possible values are:
- `daily` - This product is charged once a day.
- `weekly` - This product is charged once a week.
- `biweekly` - This product is charged once every two weeks.
- `monthly` - This product is charged once a monthy.
- `quarterly` - This product is charged once a quater (every 3 months).
- `six_monthly` - product is charged every six months.
- `annually` - This product is charged once a year.
- `unknown` - It is unknown how frequently this product is charged.
type: string
enum:
- daily
- weekly
- biweekly
- monthly
- quarterly
- six_monthly
- annually
- unknown
metadata:
title: Metadata
allOf:
- $ref: '#/components/schemas/BudDateRangeMetadata'
- type: object
required:
- results
properties:
results:
type: number
title: Results count
description: Number of products returned.
Subscription:
type: object
required:
- subscription_type
- transactions
- categories
- period
properties:
subscription_type:
type: string
description: |
Type of subscription identified. Potential values are subject to change and may be converted to enums at a future unspecified date.
| Subscription type | Description |
| --------------------------- | ----------- |
| `unknown` | Unknown subscription type |
| `media_streaming` | Digital media streaming subscriptions |
| `newspapers_and_magazines` | Print media subscriptions |
| `food_and_drink` | Grocery and specialty food/drink subscriptions |
| `technology` | Technology subscriptions, including software and hardware |
| `fitness_and_gym` | Health and fitness subscriptions |
| `charitable_donations` | Recurring donations to charity |
period:
type: string
description: To describe the period between each transaction within a subscription. Potential values could be (but are not limited to) `monthly`, `quarterly` and `unknown`, and may be converted to enums at a future unspecified date.
categories:
type: object
description: Categories of the subscription
required:
- l1
- l2
properties:
l1:
type: string
description: Details on the Level One category associated with the subscription
l2:
type: string
description: Details on the Level Two category associated with the subscription
merchant:
type: object
description: Details surrounding the identified merchant of the transaction (this field will be omitted if a merchant is not detected)
required:
- id
- name
- logo
properties:
id:
type: string
description: A unique ID for the identified merchant.
name:
type: string
description: The clean name of the identified merchant.
logo:
type: string
description: The merchant's logo image URL location.
transactions:
type: array
items:
$ref: '#/components/schemas/BasicTransactionV2'
GetSubscriptionsResponseV1:
title: Subscription Products Response
description: Subscription products and associated transactions for a customer
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- v1_subscriptions_get
data:
type: array
title: Subscriptions Finder Response Data
items:
$ref: '#/components/schemas/Subscription'
metadata:
$ref: '#/components/schemas/TransactionsResultsMetadata'
TimezoneIdentifier:
type: string
description: |-
Timezone identifier (e.g. `Europe/London`) to make dates relativised to the target location.
In the case of daylight savings in a location, this ensures that the overall start/end date accounts for those shifts.
See [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for list of valid timezone identifiers under `TZ identifier`.
default: Etc/UTC
schemas-DateTimeISO8601:
title: Date/Time (ISO 8601)
type: string
description: ISO Date Format
example: '2022-03-05T13:34:33Z'
schema:
type: string
example: 2019-02
description: Month (`YYYY-MM`) from which the transactions should be returned from, this works in pair with the `month_to` parameter.
URLMonthTo-schema:
type: string
example: 2019-03
description: Month (`YYYY-MM`) from which the transactions should be returned to, this works in pair with the `month_from` parameter.
MonthlyTotal:
required:
- month
- amount
properties:
month:
type: string
description: |
Month (format `YYYY-MM`)
amount:
$ref: '#/components/schemas/BudAmount'
TransactionsLinks:
title: Affordability Transaction Links
type: object
description: Transaction Links
required:
- transactions
properties:
transactions:
type: string
ReportTotal:
required:
- predicted_monthly
- _links
properties:
overall_total:
allOf:
- $ref: '#/components/schemas/BudAmount'
- description: |
Overall total over the report period.
monthly_totals:
type: array
items:
$ref: '#/components/schemas/MonthlyTotal'
description: |
Total per month over the report period.
predicted_monthly:
$ref: '#/components/schemas/BudAmount'
_links:
$ref: '#/components/schemas/TransactionsLinks'
IncomeAndExpenditureTransactionsLinks:
title: Income & Expenditure Transactions Links
type: object
description: Income & Expenditure Transactions Links
required:
- income_transactions
- expenditure_transactions
properties:
income_transactions:
type: string
expenditure_transactions:
type: string
MonthlyIncomeExpenditurePrediction:
title: Monthly Income & Expenditure Predictions
type: object
description: Monthly Income & Expenditure Predictions
required:
- predicted_monthly
- _links
properties:
overall_total:
allOf:
- $ref: '#/components/schemas/BudAmount'
- description: |
Overall total over the report period.
monthly_totals:
type: array
items:
$ref: '#/components/schemas/MonthlyTotal'
description: |
Total per month over the report period.
predicted_monthly:
$ref: '#/components/schemas/BudAmount'
_links:
$ref: '#/components/schemas/IncomeAndExpenditureTransactionsLinks'
MonthlyRangePrediction:
title: Monthly Range Prediction
type: object
description: Monthly Range
required:
- predicted_monthly_range
- _links
properties:
overall_total:
allOf:
- $ref: '#/components/schemas/BudAmount'
- description: |
Overall total over the report period.
monthly_totals:
type: array
items:
$ref: '#/components/schemas/MonthlyTotal'
description: |
Total per month over the report period.
predicted_monthly_range:
required:
- low
- high
- average
properties:
low:
$ref: '#/components/schemas/BudAmount'
high:
$ref: '#/components/schemas/BudAmount'
average:
$ref: '#/components/schemas/BudAmount'
_links:
$ref: '#/components/schemas/TransactionsLinks'
AffordabilityReport:
title: Retrieve Affordability Report Response
type: object
description: Retrieve Affordability Report Response Data
required:
- months_assessed
- accounts
- assessment
properties:
months_assessed:
description: Details the start and end dates for which the affordability calculation has been run
required:
- start
- end
properties:
start:
description: Date (YYYY-MM) from which the calculation should be returned from
type: string
end:
description: Date (YYYY-MM) from which the calculation should be returned to
type: string
accounts:
description: Information surrounding a given Customer's Open Banking Account(s)
required:
- connected
- holder_names
- missing_data
properties:
connected:
description: Number of accounts connected.
type: integer
holder_names:
description: Account holder names associated to connected accounts.
type: array
items:
type: string
missing_data:
description: Data from the customer that is deemed (in)sufficient for making assessments.
required:
- income
- expenditure
properties:
income:
description: Specifies if there is enough data to determine customer's income.
type: boolean
expenditure:
description: Specifies if there is enough data to determine customer's expenditure.
type: boolean
assessment:
description: A breakdown of a customers income and expenditure.
required:
- income
- expenditure
properties:
income:
description: Detailing transactions linked to a customers income
required:
- net_disposable
- net_discretionary
properties:
net_disposable:
allOf:
- description: Income -- excluding benefits -- after taxes
- $ref: '#/components/schemas/ReportTotal'
net_discretionary:
allOf:
- description: Net disposable income subtract essential expenditure
- $ref: '#/components/schemas/MonthlyIncomeExpenditurePrediction'
expenditure:
description: Detailing transactions linked to a customers expenditure
required:
- fixed
- flexible
- essential
- non_essential
properties:
fixed:
description: An expense that is a fixed amount each month
allOf:
- $ref: '#/components/schemas/ReportTotal'
flexible:
description: A regular expense that differs in amount each month
allOf:
- $ref: '#/components/schemas/MonthlyRangePrediction'
essential:
description: An expense that is not optional for a customer to pay, but isn’t necessarily the same in £ amount each month.
allOf:
- $ref: '#/components/schemas/ReportTotal'
non_essential:
description: An expense that a customer does not necessarily need to make per month, and isn’t necessarily the same in £ amount each month.
allOf:
- $ref: '#/components/schemas/ReportTotal'
V2AffordabilityReportResponse:
title: Retrieve Affordability Report Schema
type: object
description: Expected response structure
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- v2_affordability_report
data:
$ref: '#/components/schemas/AffordabilityReport'
AffordabilityReportResponse:
title: Retrieve Affordability Report Schema
type: object
description: Expected response structure
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- v1_affordability_report
data:
$ref: '#/components/schemas/AffordabilityReport'
CriteriaNetDisposableIncome:
type: string
description: |
Net Disposable Income criteria will return all transactions falling within the income category grouping. Typically includes exclusively credit transactions.
enum:
- net_disposable_income
CriteriaFixedExpenditure:
type: string
description: |
Fixed expenditure criteria will include all transactions which fall under the categories defined/expected to be consistent. Consistent in the sense of both time and financial commitment, i.e. a subscription to a healthcare provider.
enum:
- fixed_expenditure
CriteriaFlexibleExpenditure:
type: string
description: |
Flexible expenditure criteria will include all transactions which fall under the categories defined/expected to be inconsistent. inconsistent in the sense of both time and financial commitment, i.e. transactions falling under food_and_drink/eating_out_and_takeaways
enum:
- flexible_expenditure
CriteriaEssentialExpenditure:
type: string
description: |
Essential expenditure criteria will include all transactions which fall under categories deemed to be essential to a persons day to day life. These expenditure can be seen as "needs" rather than "wants". For example, food_and_drink/groceries expenditure are essential compared to shopping/hobbies.
enum:
- essential_expenditure
CriteriaNonessentialExpenditure:
type: string
description: |
Non essential expenditure criteria will include all transactions which fall under categories deemed to be non essential to a persons day to day life. These expenditure can be seen as "wants" rather than "needs". For example, shopping/hobbies expenditure are essential compared to food_and_drink/groceries.
enum:
- non_essential_expenditure
CriteriaInternalTransfers:
type: string
description: |
Internal transfers criteria returns all credit/debit transactions deemed to be made between an individual financial pool. If we drill down to the account level, wealth has been gained/lost however if we drill up we see no change in net sum.
enum:
- internal_transfers
AffordabilityCriteria:
oneOf:
- $ref: '#/components/schemas/CriteriaNetDisposableIncome'
- $ref: '#/components/schemas/CriteriaFixedExpenditure'
- $ref: '#/components/schemas/CriteriaFlexibleExpenditure'
- $ref: '#/components/schemas/CriteriaEssentialExpenditure'
- $ref: '#/components/schemas/CriteriaNonessentialExpenditure'
- $ref: '#/components/schemas/CriteriaInternalTransfers'
SpendingGroupCategories:
title: Spending Group Categories
type: object
description: Spending Group Categories
required:
- l1
- l2
properties:
l1:
description: The name of the category returned by the model.
type: string
l2:
description: The name of the sub category returned by the model.
type: string
SpendingGroupTransaction:
title: Spending Groups Transaction Response Data
type: object
description: Expected response structure
required:
- transaction_id
- account_id
- amount
- indicator
- categories
properties:
transaction_id:
description: Unique identifier for the transaction within an servicing institution. This identifier is both unique and immutable.
type: string
account_id:
description: A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner
type: string
description:
description: Further details of the transaction.
type: string
date:
description: Date and time when a transaction entry is posted to an account on the account servicer's books. ISODateTime.
type: string
format: date
indicator:
type: string
enum:
- Credit
- Debit
amount:
$ref: '#/components/schemas/LegacyBudAmount'
categories:
$ref: '#/components/schemas/SpendingGroupCategories'
criteria_satisfied:
type: array
items:
$ref: '#/components/schemas/AffordabilityCriteria'
SpendingGroupsTransactionsResponse:
title: Spending Groups Transactions Response
type: object
description: Expected response structure
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- v1_affordability_transactions_get
data:
type: array
items:
$ref: '#/components/schemas/SpendingGroupTransaction'
AffordabilityTransactionResponse:
title: Retrieve Affordability Transaction Schema
type: object
description: Expected response structure
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- v2_affordability_transactions_get
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
metadata:
type: object
required:
- results
properties:
results:
type: integer
description: The number of results returned.
next_page_token:
type: string
description: The token required to retrieve the next page of results. Will be omitted if no next page exists.
CreditDebitIndicator:
type: string
enum:
- credit
- debit
TransactionsReference:
type: string
description: |
A unique identifier to reference a specific transaction subset used within a section of a report.
schemas-TransactionsLinks:
description: URLs for resources related to this report insight
type: object
required:
- transactions
properties:
transactions:
type: string
description: |
An endpoint, including options, to make a GET request to in order to retrieve transactions
related to the report in question.
IncomeExpenditureAnalysis:
type: object
description: |
Object presents a single expenditure group income analysis report. The focus of this object is to present a
view of a single expenditure and its impact on a customers income. The report is broken down into financial months
to help identify spikes in income consumed by the expenditure group.
The type of report is identified by the `type` field. There are several types of analyses:
- income-cash-withdrawal: Identifies the total amount of cash withdrawn from a customers account.
- income-debt: Identifies debt payments in the customer's expenses.
- income-gambling: Identifies gambling related transactions in the customer's report.
- income-loan: Identifies loan related transactions.
- income-essential-expenditure: Identifies essential expenditure and compares it against income for the time period
- income-all-expenditure: Total debits vs income for a specified time period
required:
- type
- currency
- expenditure
- income
- _links
properties:
type:
type: string
enum:
- income-cash-withdrawal
- income-loan
- income-gambling
- income-debt
- income-essential-expenditure
- income-all-expenditure
description: |
A unique human readable string used to identify a expenditure group income analysis report.
Note, these are subject to change and should not be used to identify a report. These are not unique within
a result list and are used to identify the type of report.
currency:
$ref: '#/components/schemas/BudCurrency'
income:
type: object
required:
- credit_debit_indicator
- count
- total
- monthly_average
- transactions_reference
- _links
properties:
credit_debit_indicator:
$ref: '#/components/schemas/CreditDebitIndicator'
count:
type: integer
description: |
The number of transactions related to this insight.
total:
$ref: '#/components/schemas/BudAmount'
description: |
The total amount of income for the period of the report for a predefined currency.
monthly_average:
$ref: '#/components/schemas/BudAmount'
description: |
The average amount of income for the period of the report for a predefined currency.
breakdown:
type: array
items:
type: object
description: |
A breakdown of the specific transactional group for the period of the report.
The breakdown of data is defined by the granularity of the report, defaulting to monthly.
The `to`/`from` properties within the object refer to the datetime boundaries of subsection.
required:
- from
- to
- total
- count
- transactions_reference
- _links
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
total:
$ref: '#/components/schemas/BudAmount'
description: |
The total amount of expenditure for the period of the report for a predefined currency.
count:
type: integer
description: |
The number of transactions related to this insight.
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
expenditure:
type: object
required:
- credit_debit_indicator
- count
- total
- monthly_average
- relative_to_income
- transactions_reference
- _links
properties:
credit_debit_indicator:
$ref: '#/components/schemas/CreditDebitIndicator'
count:
type: integer
description: |
The number of transactions related to this insight.
total:
$ref: '#/components/schemas/BudAmount'
description: |
The total amount of expenditure for the period of the report for a predefined currency.
monthly_average:
$ref: '#/components/schemas/BudAmount'
description: |
The average amount of income for the period of the report for a predefined currency.
relative_to_income:
type: string
description: |
A percentage value to represent the scale another value is in relation to a customers income.
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
InsightOption:
title: Insight Option
type: object
description: An option used to configure the returned insights.
required:
- insight_type
- option
- value
properties:
insight_type:
type: string
description: The insight this option is applied to
option:
type: string
description: The name of the option
value:
type: string
description: The value of the option
IncomeExpenditureReportResponse:
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- insights_beta_report_income_expenditure_get
data:
type: object
required:
- insights
properties:
insights:
type: array
items:
$ref: '#/components/schemas/IncomeExpenditureAnalysis'
description: |
An array of income/expenditure analysis reports (insights). Each object in the list
represents a single insight.
metadata:
type: object
required:
- from
- to
- options
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
InsightsTransaction:
title: Transaction
type: object
description: A financial transaction
required:
- transaction_id
- account_id
- description
- amount
- credit_debit_indicator
- status
- date_time
- suggested_description
properties:
transaction_id:
type: string
description: Unique identifier for the transaction. May be mutable depending on original ingestion source.
account_id:
type: string
description: Identifier for the account associated with the transaction.
provider:
type: string
description: Name of the transaction source provider. Optional as it may not have been supplied when using first party data.
description:
type: string
description: Description of the transaction.
credit_debit_indicator:
type: string
description: Credit/Debit Indicator
enum:
- credit
- debit
status:
type: string
description: |
Status of the transaction. Defaults to booked.
Note: declined transactions are only available for transactions ingested by First Party Ingestion endpoints.
enum:
- booked
- pending
- declined
amount:
$ref: '#/components/schemas/BudAmount'
date_time:
type: string
description: Date that the transaction occured compliant with RFC3339.
posted_date_time:
type: string
deprecated: true
description: Date the assets involved in the transaction transferred compliant with RFC3339. For credits this is the date that the asset becomes available, for debits this is the date that the asset ceased to be available
value_date_time:
nullable: true
type: string
description: Date and time at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit transaction entry. ISODateTime. Null if this field is not applicable.
suggested_description:
type: string
description: The description Bud suggests client apps show for a given transaction.
suggested_logo:
type: string
description: The logo Bud suggests client apps show for a given transaction.
enrichments:
$ref: '#/components/schemas/Enrichments'
merchant_category_code:
type: string
description: Merchant category code conforming to ISO 18245, related to the type of services or goods the merchant provides for the transaction.
tags:
type: array
description: |
A list of potential tags associated with the transaction after contextual enrichment, which can be used for filtering.
Region and client specific.
| Value | Description |
|:------------------------|:----------------------------------------------------------|
| `benefit` | A government/non-profit benefit transaction |
| `debt-collection` | A transaction associated with a known debt-collector |
| `loan` | A transaction associated with a loan |
| `hcst` | A transaction associated with a high cost short term loan |
| `income` | A transaction associated with income |
| `pending` | A transaction which has not been booked |
| `regular-transaction` | A transaction predicted to occur with a regular frequency |
| `subscription` | A transaction associated with a subscription service |
| `online` | A transaction associated with an online merchant |
items:
type: string
ReportInsightsTransactionResponse:
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- insights_beta_report_income_expenditure_transactions_get
- insights_beta_report_income_health_transactions_get
- insights_beta_report_merchants_transactions_get
- insights_beta_report_unauthorised_overdraft_transactions_get
data:
type: array
description: |-
Transactions in the Bud Transactions V2 format that triggered the insight, for insights based on transaction data. If there are no specific relevant transactions, this will be an empty list.
For clients making use of the deprecated client taxonomy support, the categories in this response will be set to the client categories.
items:
$ref: '#/components/schemas/InsightsTransaction'
metadata:
type: object
required:
- from
- to
- transactions_reference
- options
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
HCSTCreditAnalysis:
type: object
description: |
Object represents analysis indicating interactions with high-cost short-term credit providers.
required:
- type
- currency
- transactions_count
- merchants_count
- transactions_reference
- _links
properties:
type:
type: string
enum:
- hcst-credit
description: |
A unique human readable string used to identify the report type.
currency:
$ref: '#/components/schemas/BudCurrency'
transactions_count:
type: integer
description: |
The number of transactions related to this insight.
merchants_count:
type: integer
description: |
The number of unique merchants related to this insight.
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
MerchantsReportResponse:
description: |
Object represents a set of merchant-related insights generated for the customer inspecting
transactions over a given period of time. The insights include:
- hcst_credit: Identifies interactions with high-cost short-term credit providers.
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- insights_beta_report_merchants_get
data:
type: object
required:
- insights
properties:
insights:
type: object
required:
- hcst_credit
properties:
hcst_credit:
type: array
items:
$ref: '#/components/schemas/HCSTCreditAnalysis'
metadata:
type: object
required:
- from
- to
- options
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
DaysInUnauthorisedOverdraft:
description: |
Object represents the number of days a customer has been in an unauthorised overdraft. Should be noted that
this is a percentage of the total number of days in the report period OR the total number of days ingested for
a given account. The report period is defined by the `from` and `to` parameters.
type: object
required:
- count
- ratio
properties:
count:
type: integer
description: |
The total number of days a customer has been in an unauthorised overdraft.
ratio:
type: string
description: |
A percentage of the numbers of unauthorised overdraft/total number of days in the report period.
UnauthorisedOverdraftDate:
type: object
required:
- date
- amount
- credit_debit_indicator
properties:
date:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
amount:
$ref: '#/components/schemas/BudAmount'
credit_debit_indicator:
$ref: '#/components/schemas/CreditDebitIndicator'
balance:
type: object
required:
- date
- type
- amount
- credit_debit_indicator
properties:
date:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
type:
description: |
Type is a string used to represent the type of balance returned, the full descriptions of each can be
found below:
https://docs.thisisbud.com/docs/accounts#balances-and-credit-lines
type: string
enum:
- closing_available
- closing_booked
- closing_cleared
- expected
- forward_available
- information
- interim_available
- interim_booked
- interim_cleared
- opening_available
- opening_booked
- opening_cleared
- previously_closed_booked
amount:
$ref: '#/components/schemas/BudAmount'
credit_debit_indicator:
$ref: '#/components/schemas/CreditDebitIndicator'
CreditLine:
type: object
required:
- date
- type
- amount
properties:
date:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
type:
type: string
description: |
Type is a string used to represent the type of creditline returned, the full descriptions of each can be
found below:
https://docs.thisisbud.com/docs/accounts#balances-and-credit-lines
enum:
- available
- credit
- emergency
- pre_agreed
- temporary
amount:
$ref: '#/components/schemas/BudAmount'
UnauthorisedOverdraftAccount:
type: object
required:
- account_id
- provider
- account_name
- days_in_unauthorised_overdraft
- unauthorised_overdraft_occurrences
- balances
- credit_lines
- transactions_reference
- _links
properties:
account_id:
type: string
description: |
A unique identifier for a specific account. The account_id can be found in the _links section of the insight report.
provider:
type: string
description: |
The name of the provider of the account.
account_name:
type: string
description: |
The name of the account.
days_in_unauthorised_overdraft:
$ref: '#/components/schemas/DaysInUnauthorisedOverdraft'
unauthorised_overdraft_occurrences:
description: |
This field contains an array of balances for the given account when its suspected the account entered an
unauthorised overdraft. The items of the array are the account balance at points in time when the customer
exceeded their credit allowance on the account.
type: array
items:
$ref: '#/components/schemas/UnauthorisedOverdraftDate'
balances:
type: array
description: |
A list of balances for the account. The balances returned here will represent the latest up to date
ingested balances for the account.
items:
$ref: '#/components/schemas/balance'
credit_lines:
type: array
description: |
A list of credit lines for the account. The credit lines returned here will represent the latest up to date
ingested balances for the account. It is possible that an account does not have any registered credit lines.
items:
$ref: '#/components/schemas/CreditLine'
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
UnauthorisedOverdraftInsight:
type: object
required:
- type
- currency
- days_in_unauthorised_overdraft
- accounts
properties:
type:
type: string
enum:
- unauthorised-overdraft
description: |
A unique human readable string used to identify a unauthorised overdraft report.
Note, these are subject to change and should not be used to identify a report. These are not unique within
a result list and are used to identify the type of report.
currency:
$ref: '#/components/schemas/BudCurrency'
days_in_unauthorised_overdraft:
$ref: '#/components/schemas/DaysInUnauthorisedOverdraft'
accounts:
type: array
items:
$ref: '#/components/schemas/UnauthorisedOverdraftAccount'
UnauthorisedOverdraftResponse:
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- insights_beta_report_balance_unauthorised_overdraft_get
data:
type: object
required:
- insights
properties:
insights:
type: array
items:
$ref: '#/components/schemas/UnauthorisedOverdraftInsight'
metadata:
type: object
required:
- from
- to
- options
- currencies
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
currencies:
type: array
description: A list of currencies returned in the results. If the currency query parameter is used, this will only contain the specified currency.
items:
$ref: '#/components/schemas/BudCurrency'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
IncomeStability:
type: object
required:
- value
- currency
properties:
value:
type: string
description: |
A number between 0 to 1 representing how stable a customers income is. The closer the number is
to 1 represents a higher stability.
currency:
$ref: '#/components/schemas/BudCurrency'
Frequency:
type: string
enum:
- daily
- weekly
- biweekly
- monthly
- quarterly
- six_monthly
- annually
- unknown
RegularTransactionIncomeGroup:
type: object
required:
- source_name
- group_id
- category_l1
- category_l2
- frequency
- total
- monthly_average
- stability
- transactions_reference
- _links
properties:
source_name:
type: string
description: A human readable to represent a regular transactional group
group_id:
type: string
format: uuid
description: a unique identifier to identify a regular transaction group
category_l1:
type: string
category_l2:
type: string
frequency:
$ref: '#/components/schemas/Frequency'
total:
$ref: '#/components/schemas/BudAmount'
monthly_average:
$ref: '#/components/schemas/BudAmount'
stability:
$ref: '#/components/schemas/IncomeStability'
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
RegularTransactions:
type: object
required:
- stability
- total
- monthly_average
- transactions_reference
- _links
- sources
properties:
stability:
$ref: '#/components/schemas/IncomeStability'
total:
$ref: '#/components/schemas/BudAmount'
monthly_average:
$ref: '#/components/schemas/BudAmount'
sources:
type: array
items:
$ref: '#/components/schemas/RegularTransactionIncomeGroup'
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
IrregularTransactions:
type: object
required:
- total
- monthly_average
- transactions_reference
- _links
properties:
total:
$ref: '#/components/schemas/BudAmount'
monthly_average:
$ref: '#/components/schemas/BudAmount'
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
IncomeHealthReportResponse:
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
type: string
enum:
- insights_beta_report_income_health_get
data:
required:
- insights
properties:
insights:
type: array
items:
description: |
An analytical report on the overall health of a customers income sources. The report presents an
overall stability, regularity, and longevity insight. In addition to this we present a drilled down insight
into the individual regular income sources for a customer. This enables a client to identify
major sources of income and their impact on the overall health of a customers income.
type: object
required:
- type
- currency
- total
- stability
- monthly_average
- regular_income
- irregular_income
- transactions_reference
- _links
properties:
type:
type: string
enum:
- income-health
currency:
$ref: '#/components/schemas/BudCurrency'
stability:
$ref: '#/components/schemas/IncomeStability'
total:
$ref: '#/components/schemas/BudAmount'
monthly_average:
$ref: '#/components/schemas/BudAmount'
regular_income:
$ref: '#/components/schemas/RegularTransactions'
irregular_income:
$ref: '#/components/schemas/IrregularTransactions'
transactions_reference:
$ref: '#/components/schemas/TransactionsReference'
_links:
$ref: '#/components/schemas/schemas-TransactionsLinks'
metadata:
type: object
required:
- from
- to
- currencies
- options
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
currencies:
type: array
description: A list of currencies returned in the results. If the currency query parameter is used, this will only contain the specified currency.
items:
$ref: '#/components/schemas/BudCurrency'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
PaymentServices:
title: Payment Services
description: A payment service supported by a payment provider
type: array
minItems: 1
items:
type: string
enum:
- domestic-single-payment
- domestic-standing-order
- domestic-scheduled-payment
PaymentSupportedCurrencies:
title: Payment provider supported currencies
description: The currencies supported by the payment provider
type: array
minItems: 1
items:
type: string
enum:
- GBP
- EUR
PaymentProvider:
title: Payment Provider
description: Information surrounding a supported payment provider
type: object
required:
- provider
- display_name
- icon
- services
- maintenance_status
- maintenance_window
- country_code
- implementation_type
- supported_currencies
- required_actions
properties:
provider:
type: string
description: The name (identifier) of the payment provider
display_name:
type: string
description: The name of the payment provider to be used for display purposes (e.g. within a frontend application)
icon:
type: string
description: A URL for the icon of the corresponding provider
services:
$ref: '#/components/schemas/PaymentServices'
maintenance_status:
type: string
description: The status of the maintenance window associated with the provider
enum:
- active
- inactive
maintenance_window:
anyOf:
- $ref: '#/components/schemas/MaintenanceWindowObject'
- type: object
nullable: true
country_code:
type: string
description: Provider country code following the ISO 3166 alpha-3 code format
implementation_type:
type: string
enum:
- OpenbankingUK
- BerlinGroup
- CBIGlobe
description: The implementation standard adopted by the provider
supported_currencies:
$ref: '#/components/schemas/PaymentSupportedCurrencies'
required_actions:
description: |
An array of enum fields to indicate if any additional actions are required in order to complete a given payment flow for the given provider.
| Value | Description |
|:-------|:-------------|
| confirm_single_payment | If present, this value indicates that clients must complete an additional step in the single payments flow whereby they must confirm the payment once the customer has successfully authorised the payment with the provider. This confirmation can be accomplished using the Confirm Single Payment API Endpoint. Please note this step is only relevant for clients using Bud as a Technical Service Provider (TSP) |
| confirm_standing_order | If present, this value indicates that clients must complete an additional step in the standing order payments flow whereby they must confirm the payment once the customer has successfully authorised the standing order with the provider. This confirmation can be accomplished using the Confirm Standing Order API Endpoint. Please note this step is only relevant for clients using Bud as a Technical Service Provider (TSP) |
| confirm_scheduled_payment | If present, this value indicates that clients must complete an additional step in the scheduled payments flow whereby they must confirm the payment once the customer has successfully authorised the scheduled order with the provider. This confirmation can be accomplished using the Confirm Scheduled Payment API Endpoint. Please note this step is only relevant for clients using Bud as a Technical Service Provider (TSP) |
items:
type: string
enum:
- confirm_single_payment
- confirm_standing_order
- confirm_scheduled_payment
PaymentProvidersResponse:
title: Payment Providers Response
type: object
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
title: Retrieve Providers
description: A list of the supported payment providers
type: array
items:
$ref: '#/components/schemas/PaymentProvider'
PaymentAccountType:
title: Account Type
type: string
description: The account type structure for the payment sender or receiver
enum:
- SortCodeAccountNumber
- IBAN
PaymentRecipient:
title: Payment Recipient
type: object
description: Details of the recipient of the payment
required:
- type
- name
- account_number
properties:
type:
$ref: '#/components/schemas/PaymentAccountType'
name:
type: string
description: Account holder name of the recipient
minLength: 1
maxLength: 70
account_number:
type: string
description: Account identifier of the recipient
minLength: 14
maxLength: 32
PaymentSender:
title: Payment Sender
type: object
description: Details of the payment sender
required:
- user_id
- name
properties:
user_id:
type: string
description: A string that can be used to uniquely identify a user within the Client's application
minLength: 1
maxLength: 120
type:
$ref: '#/components/schemas/PaymentAccountType'
name:
type: string
description: Account holder name of the sender
minLength: 1
maxLength: 70
account_number:
type: string
description: Account identifier of the sender
minLength: 14
maxLength: 32
provider:
type: string
description: The name (identifier) of the payment provider
SinglePaymentDetails:
title: Single Payment Details
type: object
description: Payment details required to make a Single Payment
required:
- reference
- recipient
- sender
- amount
properties:
reference:
type: string
description: The payment reference
recipient:
$ref: '#/components/schemas/PaymentRecipient'
sender:
$ref: '#/components/schemas/PaymentSender'
amount:
$ref: '#/components/schemas/BudAmount'
PaymentsSingleBudPayURLRequest:
title: Payments Single Bud Pay URL Payload
type: object
required:
- redirect_url
- provider
- payment_details
properties:
redirect_url:
type: string
description: URL where the user will be redirected to once they have completed the TPP Connection flow. This can be a web based URL or a mobile application internal URL.
nullable: false
maxLength: 2083
provider:
type: string
description: The name (identifier) of the payment provider
provider_types:
$ref: '#/components/schemas/ProviderTypes'
payment_details:
type: object
$ref: '#/components/schemas/SinglePaymentDetails'
BudPayResponse:
title: Bud Pay URL Response
type: object
description: Bud Pay Response Object
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
title: Bud_Pay_URL
description: Bud Pay URL Object
required:
- bud_pay_url
- payment_id
properties:
bud_pay_url:
type: string
description: A Bud Pay URL, allowing Customers to complete (authenticate) a relevant payment resource with the relevant payment service provider.
payment_id:
type: string
description: Unique identifier for the payment
PaymentStatusUpdatedNotificationBody:
title: Payment Status Update Notification Body
type: object
required:
- data
properties:
data:
description: Request which is sent to the subscribed URL when the status related to a payment has changed
required:
- event
- payment_id
- service
- user_id
properties:
payment_id:
description: The payment ID to which this event is associated
type: string
example: 19677d9f-90e7-44a6-a32e-566990623da4
service:
type: string
enum:
- domestic-single-payment
- domestic-scheduled-payment
- domestic-standing-order
description: The type of payment to which this event is related
user_id:
description: The sender.user_id provided when the payment was created
type: string
example: 19677d9f-90e7-44a6-a32e-566990623da4
event:
type: string
enum:
- payment.success
- payment.failure
description: The event related to the payment
StandingOrderFrequencyEnum:
title: Standing Order Frequency
type: string
description: The payment frequency for a Standing Order
enum:
- daily
- weekly
- fortnightly
- monthly
- quarterly
- semiannually
- yearly
StandingOrderDetails:
title: Standing Order Details
type: object
additionalProperties: false
description: Details of the standing order
required:
- reference
- recipient
- sender
- recurring_amount
- first_payment_date
- frequency
properties:
reference:
type: string
description: Reference to use for payments made through this Standing Order
maxLength: 18
recipient:
$ref: '#/components/schemas/PaymentRecipient'
sender:
$ref: '#/components/schemas/PaymentSender'
recurring_amount:
$ref: '#/components/schemas/BudAmount'
first_payment_date:
type: string
format: date-time
description: Date-time (ISO 8601) the first payment should be made. Must be a minimum of 3 business days in the future and must be on a business day.
example: '2020-06-01T15:00:00Z'
last_payment_date:
type: string
format: date-time
description: Date-time (ISO 8601) after which payments should stop. Must be after `first_payment_date`.
example: '2020-06-01T15:00:00Z'
frequency:
$ref: '#/components/schemas/StandingOrderFrequencyEnum'
PaymentsStandingOrderBudPayURLRequest:
title: Payments Standing Order Bud Pay URL Payload
type: object
required:
- redirect_url
- provider
- standing_order_details
properties:
redirect_url:
type: string
description: URL where the user will be redirected to once they have completed the TPP Connection flow. This can be a web based URL or a mobile application internal URL.
provider:
type: string
description: The name (identifier) of the payment provider
provider_types:
$ref: '#/components/schemas/ProviderTypes'
standing_order_details:
$ref: '#/components/schemas/StandingOrderDetails'
ScheduledDetails:
title: Scheduled Payment Details
type: object
additionalProperties: false
description: Details of the scheduled payment
required:
- reference
- recipient
- sender
- amount
- requested_execution_date
properties:
reference:
type: string
description: Reference to use for the payment made through this scheduled instruction
maxLength: 18
recipient:
$ref: '#/components/schemas/PaymentRecipient'
sender:
$ref: '#/components/schemas/PaymentSender'
amount:
$ref: '#/components/schemas/BudAmount'
requested_execution_date:
type: string
format: date-time
description: Date-time (ISO 8601) the payment should be made. Must be at least one day in the future.
example: '2020-06-01T15:00:00Z'
PaymentsScheduledPaymentBudPayURLRequest:
title: Scheduled Payment Bud Pay URL Payload
type: object
required:
- redirect_url
- provider
- scheduled_payment_details
properties:
redirect_url:
type: string
description: URL where the user will be redirected to once they have completed the TPP Connection flow. This can be a web based URL or a mobile application internal URL.
provider:
type: string
description: The name (identifier) of the payment provider
provider_types:
$ref: '#/components/schemas/ProviderTypes'
scheduled_payment_details:
$ref: '#/components/schemas/ScheduledDetails'
KnownCharges:
title: Known Charges
type: object
description: A list detailing information surrounding any known charges that may be associated with the payment
required:
- recipient_charge
- sender_charge
properties:
recipient_charge:
type: object
description: The charge details applied to the recipient
required:
- charge
- currency
- recipient_receives
properties:
charge:
type: string
description: A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
currency:
type: string
description: A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds"
recipient_receives:
type: string
description: A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
sender_charge:
type: object
description: The charge details applied by the sender
required:
- charge
- currency
- bank_sends
- total_cost
properties:
charge:
type: string
description: A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
currency:
type: string
description: A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds"
bank_sends:
type: string
description: A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
total_cost:
type: string
description: A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
StatusCodeEnum:
type: string
description: The payment status code
enum:
- CREATED
- AWAITING_AUTH
- AUTHENTICATED
- AUTH_REJECTED
- AUTH_COMPLETED
- FUNDS_CONFIRMED
- INSUFFICIENT_FUNDS
- INITIATING
- ACCEPTED
- SETTLED
- PAYMENT_REJECTED
- FAILED
StatusMessageEnum:
type: string
description: The payment status message
enum:
- Payment created
- Awaiting Authentication
- Authenticated; Confirming Funds
- Funds Confirmed; Awaiting Payment Initiation
- Insufficient Funds In Account; Payment Aborted
- Initiating Payment
- Payment Order Accepted
- Payment Settlement Complete
- Payment Settlement Rejected
- Failed
SupplementaryStatusDetail:
type: object
description: The payment supplementary as described by the provider
required:
- status
- history
properties:
status:
type: string
description: The status description as returned by the provide
history:
type: array
description: A list of any historical changes in the state
items:
type: object
required:
- datetime
- status
properties:
datetime:
type: string
description: A datetime string (ISO 8601) defining the date and time at which the state change occurred
status:
type: string
description: The status message
SinglePaymentStatus:
title: Single Payment Status
description: Detailed information for a given payment and it's status
type: object
required:
- payment_id
- organisation_id
- client_id
- method
- reference
- recipient
- amount
- sender
- known_charges
- state
- supplementary_status
- errors
- created_at
- required_action
properties:
payment_id:
type: string
description: Payment Identifier
organisation_id:
type: string
description: Bud's Organisation Identifier
client_id:
type: string
description: Bud's Client/App Identifier
method:
type: string
description: The payment method
enum:
- BACS
- FPS
- SEPA
reference:
type: string
description: Reference to use for this payment
maxLength: 18
recipient:
$ref: '#/components/schemas/PaymentRecipient'
amount:
$ref: '#/components/schemas/BudAmount'
sender:
$ref: '#/components/schemas/PaymentSender'
known_charges:
$ref: '#/components/schemas/KnownCharges'
state:
type: object
description: Details of the payment state and history
required:
- status_code
- status_message
- history
properties:
status_code:
$ref: '#/components/schemas/StatusCodeEnum'
status_message:
$ref: '#/components/schemas/StatusMessageEnum'
history:
type: array
items:
type: object
required:
- datetime
- code
- message
properties:
datetime:
type: string
description: A datetime string ISO 8601 defining the date and time at which the state change occurred
code:
$ref: '#/components/schemas/StatusCodeEnum'
message:
$ref: '#/components/schemas/StatusMessageEnum'
supplementary_status:
type: object
description: A list of supplementary states associated with the payment as described by the specific provider
required:
- payment_order
- consent
- confirmation_of_funds
properties:
payment_order:
$ref: '#/components/schemas/SupplementaryStatusDetail'
consent:
$ref: '#/components/schemas/SupplementaryStatusDetail'
confirmation_of_funds:
$ref: '#/components/schemas/SupplementaryStatusDetail'
errors:
title: Payment Errors
type: array
description: A list of any errors that may be associated with the payment
items:
title: Payment_Error
type: object
description: Details surrounding any error that may be associated with the payment
required:
- code
- description
properties:
code:
type: string
description: Error Code
description:
type: string
description: Text string used to give a description of the payment error
created_at:
title: Created at timestamp
type: string
description: The created at timestamp for the payment
required_action:
type: string
enum:
- confirm_single_payment
- null
nullable: true
description: |
This field will indicate that there is an action required to be taken by the client in order to complete the payment.
| Value | Description |
|:-------|:-------------|
| confirm_single_payment | If present, this value indicates that client has yet to confirm the single payment once the customer has successfully authorised the payment with the provider. This confirmation can be accomplished using the Confirm Single Payment API Endpoint. Please note this step will only be relevant for clients using Bud as a Technical Service Provider (TSP) |
ListSinglePaymentResponse:
title: List Payment Status Response
type: object
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
description: Array of Single Payment Status Objects
type: array
items:
$ref: '#/components/schemas/SinglePaymentStatus'
metadata:
type: object
description: Metadata for the response including pagination details
required:
- total_results
- results
- page
- total_pages
properties:
total_results:
type: integer
description: The total number of payment results for the request
results:
type: integer
description: The number of payment results currently displayed on the page
page:
type: integer
description: The current page number
total_pages:
type: integer
description: The total number of pages for the request
SinglePaymentRequest:
title: Single Payment Request Payload
type: object
description: Expected request payload structure
required:
- provider
- payment_details
properties:
redirect_url:
type: string
description: This is the url that your Customer will be redirected to when using the Bud user interface. If you wish to use your own license and callback infrastructure this parameter will have no effect and the provider_redirect_url parameter should be used instead.
provider_redirect_url:
type: string
description: This is the url that your Customer will be redirected to once they have authorised with the relevant provider. This should only be used when using your own license and wish to use the Submit Authorisation Codes endpoint. If you wish to use Bud's call back then the redirect_url must be provided.
provider:
type: string
description: The name (identifier) of the payment provider
payment_details:
$ref: '#/components/schemas/SinglePaymentDetails'
SinglePaymentResponse:
title: Single Payment Response
type: object
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
description: Single Payment Response
required:
- authorisation_url
- payment_id
properties:
authorisation_url:
type: string
description: The authorisation URL for a relevant payment provider. Redirect your Customer to this url to allow them to authorise their payment
payment_id:
type: string
description: Unique identifier for the single payment resource
required_action:
type: string
description: |
If present, this fild will indicate the next required action (if any) to be taken by the client in order to complete the payment flow
| Value | Description |
|:-------|:-------------|
| confirm_single_payment | Indicates that the client must confirm the single payment using the Confirm Single Payment endpoint in order to complete the payment flow. |
enum:
- confirm_single_payment
PaymentsAuthorisationCodesResponse:
title: Authorisation Codes Response Payload
type: object
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
description: Details regarding the response object for the authorisation codes response.
properties:
result:
type: string
enum:
- success
- auth_invalid
- auth_expired
- provider_failure
- internal_error
payment_id:
type: string
description: Payment Identifier
payment_type:
type: string
description: The type of payment iniated through Bud's Payments Service
enum:
- single
- scheduled
- standing-order
PaymentsErrorResponse:
type: object
description: Payments Error Response
required:
- operation_id
- code_id
- message
- errors
properties:
operation_id:
type: string
enum:
- v1_payments_providers_get
- v1_payments_single_get
- v1_payments_single_post
- v1_payments_single_payment_id_auth_token_post
- v1_payments_single_payment_id_get
- v1_payments_single_confirm_post
- v1_payments_authorisation_codes_post
code_id:
type: string
enum:
- failed_validation
- internal_error
- not_found
- provider_in_maintenance_mode
message:
type: string
enum:
- Failed validation
- Internal server error has occurred
- Resource not found
- '[ProviderName] is currently in a maintenance mode, please try again later.'
errors:
type: object
StatusSinglePaymentResponse:
title: Payment Status Response
type: object
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/SinglePaymentStatus'
StandingOrderStatusCodeEnum:
title: Standing Order Status Codes
type: string
description: The payment status code for a Standing Order
enum:
- CREATED
- AWAITING_AUTH
- AUTH_REJECTED
- AUTH_COMPLETED
- PENDING
- FAILED
- COMPLETED
StandingOrderStatusMessageEnum:
title: Standing Order Status Message
type: string
description: The payment status message for a Standing Order
enum:
- Standing Order Created
- Awaiting Customer Authentication
- Authentication Failed
- Authentication Completed
- Payment Order Pending
- Standing Order Creation Failed
- Standing Order Creation Completed
StandingOrderData:
title: Standing Order Data
type: object
description: Data structure for the Standing Order object
required:
- payment_id
- organisation_id
- client_id
- reference
- recipient
- recurring_amount
- sender
- known_charges
- state
- errors
- created_at
- frequency
- first_payment_date
- required_action
properties:
payment_id:
type: string
description: Payment Identifier
organisation_id:
type: string
description: Bud's Organisation Identifier
client_id:
type: string
description: Bud's Client/App Identifier
reference:
type: string
description: Reference to use for this payment
recipient:
$ref: '#/components/schemas/PaymentRecipient'
recurring_amount:
$ref: '#/components/schemas/BudAmount'
sender:
$ref: '#/components/schemas/PaymentSender'
known_charges:
$ref: '#/components/schemas/KnownCharges'
state:
type: object
required:
- status_code
- status_message
- history
properties:
status_code:
$ref: '#/components/schemas/StandingOrderStatusCodeEnum'
status_message:
$ref: '#/components/schemas/StandingOrderStatusMessageEnum'
history:
type: array
items:
type: object
required:
- datetime
- code
- message
properties:
datetime:
type: string
code:
$ref: '#/components/schemas/StandingOrderStatusCodeEnum'
message:
$ref: '#/components/schemas/StandingOrderStatusMessageEnum'
errors:
type: array
description: Details surrounding any errors when attempting to initiate a Standing Order
items:
type: object
required:
- code
- description
properties:
code:
type: string
description: Error Code
description:
type: string
description: Text string used to give a description of the payment error
created_at:
type: string
format: date-time
description: Date-time (ISO 8601) of when the Standing Order was created
example: '2020-06-01T15:00:00Z'
first_payment_date:
type: string
format: date-time
description: Date-time (ISO 8601) the first payment should be made. Must be future date.
example: '2020-06-01T15:00:00Z'
last_payment_date:
type: string
format: date-time
description: Date-time (ISO 8601) after which payments should stop. Must be after `first_payment_date`.
example: '2020-06-01T15:00:00Z'
frequency:
$ref: '#/components/schemas/StandingOrderFrequencyEnum'
required_action:
type: string
nullable: true
description: |
This field will indicate that there is an action required to be taken by the client in order to complete the payment.
| Value | Description |
|:-------|:-------------|
| confirm_standing_order | If present, this value indicates that client has yet to confirm the standing order once the customer has successfully authorised the payment with the provider. This confirmation can be accomplished using the Confirm Standing Order API Endpoint. Please note this step will only be relevant for clients using Bud as a Technical Service Provider (TSP) |
enum:
- confirm_standing_order
- null
ListStandingOrderResponse:
title: List Standing Order Response
type: object
description: Response structure when retrieving a filtered list of Standing Order status'
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
description: Array of Standing Order Payment Status Objects
type: array
items:
$ref: '#/components/schemas/StandingOrderData'
metadata:
description: Metadata associated with response
type: object
required:
- total_results
- results
- page
- total_pages
properties:
total_results:
type: integer
description: The total number of payment results for the request
results:
type: integer
description: The number of payment results currently displayed on the page
page:
type: integer
description: The current page number
total_pages:
type: integer
description: The total number of pages for the request
CreateStandingOrderRequest:
title: Create Standing Order Request
type: object
required:
- provider
- standing_order_details
properties:
redirect_url:
type: string
description: This is the url that your Customer will be redirected to when using the Bud user interface. If you wish to use your own license and callback infrastructure this parameter will have no effect and the provider_redirect_url parameter should be used instead.
provider_redirect_url:
type: string
description: This is the url that your Customer will be redirected to once they have authorised with the relevant provider. This should only be used when using your own license and wish to use the Submit Authorisation Codes endpoint. If you wish to use Bud's call back then the redirect_url must be provided.
provider:
type: string
description: The name (identifier) of the payment provider
provider_types:
$ref: '#/components/schemas/ProviderTypes'
standing_order_details:
$ref: '#/components/schemas/StandingOrderDetails'
CreateStandingOrderResponse:
title: Create Standing Order Response
type: object
description: Response structure when creating a Standing Order payment
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
description: Standing Order Response Object
required:
- payment_id
- authorisation_url
properties:
payment_id:
type: string
description: Payment Identifier
authorisation_url:
type: string
description: The authorisation URL for a relevant payment provider. Redirect your Customer to this url to allow them to authorise the Standing Order
required_action:
type: string
description: |
If present, this fild will indicate the next required action (if any) to be taken by the client in order to complete the payment flow
| Value | Description |
|:-------|:-------------|
| confirm_standing_order | Indicates that the client must confirm the standing order using the Confirm Standing Order endpoint in order to complete the payment flow. |
enum:
- confirm_standing_order
StatusStandingOrderResponse:
title: Standing Order Status Response
type: object
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/StandingOrderData'
ScheduledPaymentStatusCodeEnum:
title: Scheduled Payment Status Codes
type: string
description: The payment status code for a Scheduled Payment
enum:
- CREATED
- AWAITING_AUTH
- AUTH_REJECTED
- AUTH_COMPLETED
- PENDING
- FAILED
- COMPLETED
ScheduledPaymentStatusMessageEnum:
title: Scheduled Payment Status Message
type: string
description: The payment status message for a Scheduled Payment
enum:
- Scheduled Payment Created
- Awaiting Customer Authentication
- Authentication Failed
- Authentication Completed
- Payment Order Pending
- Scheduled Payment Creation Failed
- Scheduled Payment Creation Completed
ScheduledPaymentData:
title: Scheduled Payment Data
type: object
description: Data structure for the Scheduled Payment object
required:
- payment_id
- organisation_id
- client_id
- reference
- recipient
- sender
- known_charges
- state
- errors
- created_at
- requested_execution_date
properties:
payment_id:
type: string
description: Payment Identifier
organisation_id:
type: string
description: Bud's Organisation Identifier
client_id:
type: string
description: Bud's Client/App Identifier
reference:
type: string
description: Reference to use for this payment
recipient:
$ref: '#/components/schemas/PaymentRecipient'
recurring_amount:
$ref: '#/components/schemas/BudAmount'
sender:
$ref: '#/components/schemas/PaymentSender'
known_charges:
$ref: '#/components/schemas/KnownCharges'
state:
type: object
required:
- status_code
- status_message
- history
properties:
status_code:
$ref: '#/components/schemas/ScheduledPaymentStatusCodeEnum'
status_message:
$ref: '#/components/schemas/ScheduledPaymentStatusMessageEnum'
history:
type: array
items:
type: object
required:
- datetime
- code
- message
properties:
datetime:
type: string
code:
$ref: '#/components/schemas/ScheduledPaymentStatusCodeEnum'
message:
$ref: '#/components/schemas/ScheduledPaymentStatusMessageEnum'
errors:
type: array
description: Details surrounding any errors when attempting to initiate a Scheduled Payment
items:
type: object
required:
- code
- description
properties:
code:
type: string
description: Error Code
description:
type: string
description: Text string used to give a description of the payment error
created_at:
type: string
format: date-time
description: Date-time (ISO 8601) of when the Scheduled Payment was created
example: '2020-06-01T15:00:00Z'
requested_execution_date:
type: string
format: date-time
description: Date-time (ISO 8601) the Scheduled Payment should be made. Must be future date.
example: '2020-06-01T15:00:00Z'
required_action:
type: string
nullable: true
description: |
This field will indicate that there is an action required to be taken by the client in order to complete the payment.
| Value | Description |
|:-------|:-------------|
| confirm_scheduled_payment | If present, this value indicates that client has yet to confirm the Scheduled Payment once the customer has successfully authorised the payment with the provider. This confirmation can be accomplished using the Confirm Scheduled Payment API Endpoint. Please note this step will only be relevant for clients using Bud as a Technical Service Provider (TSP) |
enum:
- confirm_scheduled_payment
- null
ListScheduledPaymentResponse:
title: List Scheduled Payment Response
type: object
description: Response structure when retrieving a filtered list of Scheduled Payment status'
required:
- operation_id
- data
- metadata
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
description: Array of Scheduled Payment Status Objects
type: array
items:
$ref: '#/components/schemas/ScheduledPaymentData'
metadata:
description: Metadata associated with response
type: object
required:
- total_results
- results
- page
- total_pages
properties:
total_results:
type: integer
description: The total number of payment results for the request
results:
type: integer
description: The number of payment results currently displayed on the page
page:
type: integer
description: The current page number
total_pages:
type: integer
description: The total number of pages for the request
CreateScheduledPaymentRequest:
title: Create Scheduled Payment Request
type: object
required:
- provider
- scheduled_payment_details
properties:
redirect_url:
type: string
description: This is the url that your Customer will be redirected to when using the Bud user interface. If you wish to use your own license and callback infrastructure this parameter will have no effect and the provider_redirect_url parameter should be used instead.
provider_redirect_url:
type: string
description: This is the url that your Customer will be redirected to once they have authorised with the relevant provider. This should only be used when using your own license and wish to use the Submit Authorisation Codes endpoint. If you wish to use Bud's call back then the redirect_url must be provided.
provider:
type: string
description: The name (identifier) of the payment provider
provider_types:
$ref: '#/components/schemas/ProviderTypes'
scheduled_payment_details:
$ref: '#/components/schemas/ScheduledDetails'
CreateScheduledPaymentResponse:
title: Create Scheduled Payment Response
type: object
description: Response structure when creating a Scheduled Payment
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
type: object
description: Scheduled Payment Response Object
required:
- payment_id
- authorisation_url
properties:
payment_id:
type: string
description: Payment Identifier
authorisation_url:
type: string
description: The authorisation URL for a relevant payment provider. Redirect your Customer to this url to allow them to authorise the scheduled instruction
required_action:
type: string
nullable: true
description: |
If present, this fild will indicate the next required action (if any) to be taken by the client in order to complete the payment flow
| Value | Description |
|:-------|:-------------|
| confirm_scheduled_payment | Indicates that the client must confirm the scheduled payment using the Confirm Scheduled Payment endpoint in order to complete the payment flow. |
enum:
- confirm_scheduled_payment
GetScheduledPaymentResponse:
title: Get Scheduled Payment Response
type: object
description: Response structure when retrieving a specific Scheduled Payment status
required:
- operation_id
- data
properties:
operation_id:
$ref: '#/components/schemas/OperationId'
data:
$ref: '#/components/schemas/ScheduledPaymentData'
metadata:
type: object
CustomerCharacteristicSimple:
title: Customer Characteristic
type: object
properties:
type:
title: Characteristic Type
type: string
description: |
The type of customer characteristic. Currently supported values include:
- `credit_card`
- `loan`
- `overdraft`
- `saver`
However clients integrating with this endpoint should expect more to be added without notice.
link:
title: Characteristic Details Link
type: string
description: The URL to follow to get detailed Characteristic information about the customer.
GetCustomerCharacteristicsResponse:
title: Retrieve Customer Characteristics Response
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- characteristics_v1_customer_get
data:
type: array
items:
$ref: '#/components/schemas/CustomerCharacteristicSimple'
components_schemas-Categories:
title: Categories
type: object
description: |
Categories enrichment associated with a Transaction, as generated by Bud's artificial intelligence models.
Currently two levels of category are supported, with `l1` being a coarse-grained category level and `l2` being more refined.
properties:
l1:
$ref: '#/components/schemas/Category'
description: Level 1 Category
l2:
$ref: '#/components/schemas/Category'
description: Level 2 Category
CustomerCharacteristicTransaction:
title: Customer Characteristic Transaction
type: object
description: A financial transaction
required:
- transaction_id
- account_id
- description
- amount
- credit_debit_indicator
- status
- date_time
properties:
transaction_id:
type: string
description: Unique identifier for the transaction. May be mutable depending on original ingestion source.
account_id:
type: string
description: Identifier for the account associated with the transaction.
provider:
type: string
description: Name of the transaction source provider. Optional as it may not have been supplied when using first party data.
description:
type: string
description: Description of the transaction.
credit_debit_indicator:
type: string
description: Credit/Debit Indicator
enum:
- credit
- debit
status:
type: string
description: Status of the transaction. Defaults to booked.
enum:
- booked
- pending
amount:
$ref: '#/components/schemas/BudAmount'
date_time:
type: string
description: Date of the transaction compliant with RFC3339.
enrichments:
type: object
description: Contextual enrichments associated with a Transaction
properties:
categories:
$ref: '#/components/schemas/components_schemas-Categories'
TransactionTotal:
type: object
description: Totals of all included transactions for the specified currency.
required:
- amount
- credit_debit_indicator
properties:
amount:
$ref: '#/components/schemas/BudAmount'
credit_debit_indicator:
type: string
description: Credit/Debit Indicator
enum:
- credit
- debit
GetCreditCardCharacteristicsResponse:
title: Get Credit Card Customer Characteristics Response
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- characteristics_v1_customer_credit_card_get
data:
type: object
properties:
credit_card_transactions:
type: array
items:
$ref: '#/components/schemas/CustomerCharacteristicTransaction'
credit_card_transaction_totals:
type: array
items:
$ref: '#/components/schemas/TransactionTotal'
GetLoanCharacteristicsResponse:
title: Get Loan Customer Characteristics Response
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- characteristics_v1_customer_loan_get
data:
type: object
properties:
loan_transactions:
type: array
items:
$ref: '#/components/schemas/CustomerCharacteristicTransaction'
loan_transaction_totals:
type: array
items:
$ref: '#/components/schemas/TransactionTotal'
GetOverdraftCharacteristicsResponse:
title: Get Overdraft Customer Characteristics Response
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- characteristics_v1_customer_overdraft_get
data:
type: object
properties:
overdraft_transactions:
type: array
items:
$ref: '#/components/schemas/CustomerCharacteristicTransaction'
overdraft_transaction_totals:
type: array
items:
$ref: '#/components/schemas/TransactionTotal'
GetSaverCharacteristicsResponse:
title: Get Saver Customer Characteristics Response
type: object
required:
- operation_id
- data
properties:
operation_id:
type: string
enum:
- characteristics_v1_customer_saver_get
data:
type: object
properties:
saver_transactions:
type: array
items:
$ref: '#/components/schemas/CustomerCharacteristicTransaction'
saver_transaction_totals:
type: array
items:
$ref: '#/components/schemas/TransactionTotal'
InsightLinks:
title: Links
description: URLs for resources related to this insight
type: object
required:
- details
properties:
details:
type: string
description: An endpoint, including options, to make a GET request to in order to retrieve insight-specific details for this insight, and the transaction and account data that caused it to trigger.
CommonInsightResponse:
title: Common Insight Response
description: Common parts of an identified insight, shared across all identified insights
type: object
required:
- id
- type
- _links
properties:
id:
type: string
description: An ID for this returned insight. Will be unique within the response, and consistent until financial data is refreshed. For a customised insights request, this will only be consistent across requests specifying the same configuration.
type:
type: string
description: The type of insight triggered. Specifies the meaning of the insight, and the format of the additional_info object.
example: gambling_threshold
_links:
$ref: '#/components/schemas/InsightLinks'
AmountWithCDI:
title: Credit Debit Indicator
type: object
description: An amount of money, in a specific currency with a credit/debit indicator.
required:
- currency
- value
- credit_debit_indicator
properties:
currency:
$ref: '#/components/schemas/BudCurrency'
value:
$ref: '#/components/schemas/BudMonetaryValue'
credit_debit_indicator:
$ref: '#/components/schemas/CreditDebitIndicator'
BalancesInsightResponse:
title: Balances Insight Response
description: Balances insight identified from the customer's financial data
allOf:
- $ref: '#/components/schemas/CommonInsightResponse'
- type: object
required:
- account_id
- balance
- threshold
properties:
account_id:
type: string
description: The account ID whose current, projected, or past balance information this insight relates to.
balance:
$ref: '#/components/schemas/AmountWithCDI'
threshold:
$ref: '#/components/schemas/AmountWithCDI'
BalancesInsightsResponse:
title: Balances Insights Response
description: Balances insights response, providing identified balances insights for this customer.
type: object
required:
- data
- operation_id
- metadata
properties:
operation_id:
type: string
enum:
- insights_v1_actionable_balances_get
data:
type: object
required:
- insights
properties:
insights:
type: array
items:
$ref: '#/components/schemas/BalancesInsightResponse'
metadata:
type: object
required:
- results
- from
- to
- options
properties:
results:
type: integer
description: Number of insights returned in the response.
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
InsightCausedBy:
title: Caused By
description: The financial data that resulted in this insight being triggered, to which it can be attributed.
type: object
required:
- transactions
- accounts
properties:
accounts:
type: array
description: Accounts in the Bud Accounts V2 format that triggered the insight, for insights based on account and balance data. If there are no specific relevant accounts, this will be an empty list.
items:
$ref: '#/components/schemas/AccountV2'
transactions:
type: array
description: |-
Transactions in the Bud Transactions V2 format that triggered the insight, for insights based on transaction data. If there are no specific relevant transactions, this will be an empty list.
For clients making use of the deprecated client taxonomy support, the categories in this response will be set to the client categories.
items:
$ref: '#/components/schemas/InsightsTransaction'
CommonInsightDataResponseNoDetails:
title: Common Insight Details Response
description: Common parts of the insight details response, shared by all insight types
type: object
required:
- id
- type
- caused_by
properties:
id:
type: string
description: An ID for this returned insight. Will be unique within the response, and consistent until financial data is refreshed. For a customised insights request, this will only be consistent across requests specifying the same configuration.
type:
type: string
description: The type of insight triggered. Specifies the meaning of the insight, and the format of the additional_info object.
example: late_income
caused_by:
$ref: '#/components/schemas/InsightCausedBy'
CannotCoverBillsInsightDetails:
title: Cannot Cover Bills Insight Details
description: Details for a 'cannot cover bills' insight
type: object
properties:
expected_debit:
$ref: '#/components/schemas/BudAmount'
expected_credit:
$ref: '#/components/schemas/BudAmount'
date_time:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
current_balance:
$ref: '#/components/schemas/BudAmount'
CannotCoverBillsInsightDataResponse:
title: Cannot Cover Bills Insight Details Response
description: Details response for a 'cannot cover bills' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- cannot_cover_bills
details:
$ref: '#/components/schemas/CannotCoverBillsInsightDetails'
CloseToCreditLimitInsightDetails:
title: Close To Credit Limit Insight Details
description: Details for a 'close to credit limit' insight
type: object
properties:
percentage_utilisation:
type: string
description: Percentage (to 2 decimal places) of the credit limit that is currently being used.
CloseToCreditLimitInsightDataResponse:
title: Close To Credit Limit Insight Details Response
description: Details response for a 'close to credit limit' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- close_to_credit_limit
details:
$ref: '#/components/schemas/CloseToCreditLimitInsightDetails'
InOverdraftInsightDataResponse:
title: In Overdraft Insight Details Response
description: Details response for an 'in overdraft' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- in_overdraft
details:
type: object
additionalProperties: false
description: Always empty for this insight type.
LowBalanceInsightDataResponse:
title: Low Balance Insight Details Response
description: Details response for a low balance insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- low_balance
details:
type: object
additionalProperties: false
description: Always empty for this insight type.
BalancesInsightsDataResponse:
title: Balances Insight Details Response
description: Details response for a balances insight
type: object
required:
- data
- operation_id
- metadata
properties:
operation_id:
type: string
enum:
- insights_v1_actionable_balances_details_get
data:
oneOf:
- $ref: '#/components/schemas/CannotCoverBillsInsightDataResponse'
- $ref: '#/components/schemas/CloseToCreditLimitInsightDataResponse'
- $ref: '#/components/schemas/InOverdraftInsightDataResponse'
- $ref: '#/components/schemas/LowBalanceInsightDataResponse'
metadata:
type: object
required:
- from
- to
- options
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
IncomeInsightResponse:
title: Income Insight Response
description: Income insight identified from the customer's financial data
allOf:
- $ref: '#/components/schemas/CommonInsightResponse'
- type: object
required:
- transactions
properties:
transactions:
type: array
description: The transaction or transactions that most immediately triggered the insight, in our Transactions V2 format.
items:
$ref: '#/components/schemas/InsightsTransaction'
TransactionTotals:
title: Transaction Totals
description: Total income and expenses for the customer across the period checked for insights
type: object
required:
- income
- expenditure
properties:
income:
type: array
description: The total income for the period, in every currency that had an insight trigger within the period.
items:
$ref: '#/components/schemas/BudAmount'
expenditure:
type: array
description: The total expenses for the period, in every currency that had an insight trigger within the period.
items:
$ref: '#/components/schemas/BudAmount'
IncomeInsightOption:
title: Insight Option
type: object
description: An option used to configure the returned insights.
required:
- insight_type
- option
- value
properties:
insight_type:
type: string
description: The insight this option is applied to
option:
type: string
description: The name of the option
value:
description: The value of the option
IncomeInsightsResponse:
title: Income Insights Response
description: Income insights response, providing identified income insights for this customer.
type: object
required:
- data
- operation_id
- metadata
properties:
operation_id:
type: string
enum:
- insights_v1_actionable_income_get
data:
type: object
required:
- insights
- totals
properties:
insights:
type: array
items:
$ref: '#/components/schemas/IncomeInsightResponse'
totals:
$ref: '#/components/schemas/TransactionTotals'
metadata:
type: object
required:
- results
- from
- to
- options
properties:
results:
type: integer
description: Number of insights returned in the response.
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
options:
type: array
items:
$ref: '#/components/schemas/IncomeInsightOption'
GamblingIncomeInsightDetails:
title: Gambling Income Insight Details
description: Details for a 'gambling income' insight
type: object
properties:
total:
$ref: '#/components/schemas/BudAmount'
GamblingIncomeInsightDataResponse:
title: Gambling Income Insight Details Response
description: Details response for a 'gambling income' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- gambling_income
details:
$ref: '#/components/schemas/GamblingIncomeInsightDetails'
LateIncomeInsightDetails:
title: Late Income Insight Details
description: Details for a 'late income' insight
type: object
properties:
days_late:
type: number
description: Number of days since the predicted transaction was expected to occur.
expected_date_time:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
LateIncomeInsightDataResponse:
title: Late Income Insight Details Response
description: Details response for a 'late income' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- late_income
details:
$ref: '#/components/schemas/LateIncomeInsightDetails'
PensionIncomeInsightDetails:
title: Pension Income Insight Details
description: Details for a 'pension income' insight
type: object
properties:
total:
$ref: '#/components/schemas/BudAmount'
PensionIncomeInsightDataResponse:
title: Pension Income Insight Details Response
description: Details response for a 'pension income' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- pension_income
details:
$ref: '#/components/schemas/PensionIncomeInsightDetails'
RegularIncomeChangedInsightDetails:
title: Regular Income Changed Insight Details
description: Details for a 'regular income changed' insight
type: object
properties:
new_amount:
$ref: '#/components/schemas/BudAmount'
absolute_change:
$ref: '#/components/schemas/BudMonetaryValue'
percentage_change:
$ref: '#/components/schemas/BudMonetaryValue'
RegularIncomeChangedInsightDataResponse:
title: Regular Income Changed Insight Details Response
description: Details response for a 'regular income changed' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
properties:
type:
type: string
enum:
- regular_income_changed
details:
$ref: '#/components/schemas/RegularIncomeChangedInsightDetails'
IncomeInsightsDataResponse:
title: Income Insight Details Response
description: Details response for an income insight
type: object
required:
- data
- operation_id
- metadata
properties:
operation_id:
type: string
enum:
- insights_v1_actionable_income_details_get
data:
oneOf:
- $ref: '#/components/schemas/GamblingIncomeInsightDataResponse'
- $ref: '#/components/schemas/LateIncomeInsightDataResponse'
- $ref: '#/components/schemas/PensionIncomeInsightDataResponse'
- $ref: '#/components/schemas/RegularIncomeChangedInsightDataResponse'
metadata:
type: object
required:
- from
- to
- options
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
SpendingInsightResponse:
title: Spending Insight Response
description: Spending insight identified from the customer's financial data
allOf:
- $ref: '#/components/schemas/CommonInsightResponse'
- type: object
required:
- transactions
properties:
transactions:
type: array
description: The transaction or transactions that most immediately triggered the insight, in our Transactions V2 format.
items:
$ref: '#/components/schemas/InsightsTransaction'
SpendingInsightsResponse:
title: Spending Insights Response
description: Spending insights response, providing identified balances insights for this customer.
type: object
required:
- data
- operation_id
- metadata
properties:
operation_id:
type: string
enum:
- insights_v1_actionable_spending_get
data:
type: object
required:
- insights
- totals
properties:
insights:
type: array
items:
$ref: '#/components/schemas/SpendingInsightResponse'
totals:
$ref: '#/components/schemas/TransactionTotals'
metadata:
type: object
required:
- results
- from
- to
- options
properties:
results:
type: integer
description: Number of insights returned in the response.
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
LatePaymentInsightDetails:
title: Late Payment Insight Details
description: Details for a 'late payment' insight
type: object
properties:
days_late:
type: number
description: Number of days since the predicted transaction was expected to occur.
expected_date_time:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
LatePaymentInsightDataResponse:
title: Late Payment Insight Details Response
description: Details response for a 'late payment' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- late_payment
details:
$ref: '#/components/schemas/LatePaymentInsightDetails'
NewInsuranceExpenseInsightDataResponse:
title: New Insurance Expense Insight Details Response
description: Details response for a 'new insurance expense' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- new_insurance_expense
details:
type: object
additionalProperties: false
description: Always empty for this insight type.
RegularPaymentChangedInsightDetails:
title: Regular Payment Changed Insight Details
description: Details for a 'regular payment changed' insight
type: object
properties:
new_amount:
$ref: '#/components/schemas/BudAmount'
absolute_change:
$ref: '#/components/schemas/BudMonetaryValue'
percentage_change:
$ref: '#/components/schemas/BudMonetaryValue'
RegularPaymentChangedInsightDataResponse:
title: Regular Payment Changed Insight Details Response
description: Details response for a 'regular payment changed' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- regular_payment_changed
details:
$ref: '#/components/schemas/RegularPaymentChangedInsightDetails'
SuspectedDuplicateChargeInsightDataResponse:
title: Suspected Duplicate Charge Insight Details Response
description: Details response for a 'suspected duplicate charge' insight
allOf:
- $ref: '#/components/schemas/CommonInsightDataResponseNoDetails'
- type: object
required:
- details
properties:
type:
type: string
enum:
- suspected_duplicate_charge
details:
type: object
additionalProperties: false
description: Always empty for this insight type.
SpendingInsightsDataResponse:
title: Spending Insight Details Response
description: Details response for a spending insight
type: object
required:
- data
- operation_id
- metadata
properties:
operation_id:
type: string
enum:
- insights_v1_actionable_spending_details_get
data:
oneOf:
- $ref: '#/components/schemas/LatePaymentInsightDataResponse'
- $ref: '#/components/schemas/NewInsuranceExpenseInsightDataResponse'
- $ref: '#/components/schemas/RegularPaymentChangedInsightDataResponse'
- $ref: '#/components/schemas/SuspectedDuplicateChargeInsightDataResponse'
metadata:
type: object
required:
- from
- to
- options
properties:
from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
options:
type: array
items:
$ref: '#/components/schemas/InsightOption'
GenerateCardSummaryURLRequest:
type: object
required:
- summary_type
properties:
summary_type:
type: string
enum:
- weekly
- monthly
- quarterly
GenerateCardSummaryURLResponse:
type: object
properties:
operation_id:
type: string
enum:
- insights_v1_summary_url_post
data:
type: object
properties:
url:
type: string
format: uri
metadata:
type: object
properties:
sufficient_data:
type: boolean
number_of_insights:
type: integer
summary_to:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
summary_from:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
BaseHeadingLevel:
type: integer
minimum: 1
maximum: 6
ColorMode:
type: string
enum:
- system
- light
- dark
GlobalWidgetURLQueryParams:
type: object
properties:
base_heading_level:
$ref: '#/components/schemas/BaseHeadingLevel'
color_mode:
$ref: '#/components/schemas/ColorMode'
FinancialCalendarQueryParams:
allOf:
- $ref: '#/components/schemas/GlobalWidgetURLQueryParams'
GenerateFinancialCalendarURLRequest:
type: object
properties:
additional_query_params:
$ref: '#/components/schemas/FinancialCalendarQueryParams'
GenerateFinancialCalendarURLResponse:
type: object
properties:
operation_id:
type: string
enum:
- insights_v1_financial_calendar_url_post
data:
type: object
properties:
url:
type: string
format: uri
metadata:
type: object
properties:
sufficient_data:
type: boolean
BalancesOverTimeQueryParams:
allOf:
- $ref: '#/components/schemas/GlobalWidgetURLQueryParams'
GenerateBalancesOverTimeURLRequest:
type: object
properties:
additional_query_params:
$ref: '#/components/schemas/BalancesOverTimeQueryParams'
GenerateBalancesOverTimeURLResponse:
type: object
properties:
operation_id:
type: string
enum:
- insights_v1_balances_over_time_url_post
data:
type: object
properties:
url:
type: string
format: uri
metadata:
type: object
properties:
sufficient_data:
type: boolean
RecurringAndForecastedTransactionsQueryParams:
allOf:
- $ref: '#/components/schemas/GlobalWidgetURLQueryParams'
GenerateRecurringAndForecastedTransactionsURLRequest:
type: object
properties:
additional_query_params:
$ref: '#/components/schemas/RecurringAndForecastedTransactionsQueryParams'
GenerateRecurringAndForecastedTransactionsURLResponse:
type: object
properties:
operation_id:
type: string
enum:
- insights_v1_recurring_and_forecasted_transactions_url_post
data:
type: object
properties:
url:
type: string
format: uri
metadata:
type: object
properties:
sufficient_data:
type: boolean
SpendingAnalysisQueryParams:
allOf:
- $ref: '#/components/schemas/GlobalWidgetURLQueryParams'
GenerateSpendingAnalysisURLRequest:
type: object
properties:
additional_query_params:
$ref: '#/components/schemas/SpendingAnalysisQueryParams'
GenerateSpendingAnalysisURLResponse:
type: object
properties:
operation_id:
type: string
enum:
- insights_v1_spending_analysis_url_post
data:
type: object
properties:
url:
type: string
format: uri
metadata:
type: object
properties:
sufficient_data:
type: boolean
SpendingBudgetsQueryParams:
allOf:
- $ref: '#/components/schemas/GlobalWidgetURLQueryParams'
GenerateSpendingBudgetsURLRequest:
type: object
properties:
additional_query_params:
$ref: '#/components/schemas/SpendingBudgetsQueryParams'
GenerateSpendingBudgetsURLResponse:
type: object
properties:
operation_id:
type: string
enum:
- insights_v1_spending_budgets_url_post
data:
type: object
properties:
url:
type: string
format: uri
metadata:
type: object
properties:
sufficient_data:
type: boolean
SavingsGoalsQueryParams:
allOf:
- $ref: '#/components/schemas/GlobalWidgetURLQueryParams'
GenerateSavingsGoalsURLRequest:
type: object
properties:
additional_query_params:
$ref: '#/components/schemas/SavingsGoalsQueryParams'
GenerateSavingsGoalsURLResponse:
type: object
properties:
operation_id:
type: string
enum:
- insights_v1_savings_goals_url_post
data:
type: object
properties:
url:
type: string
format: uri
metadata:
type: object
properties:
sufficient_data:
type: boolean
IntelligentSearchQueryParams:
allOf:
- $ref: '#/components/schemas/GlobalWidgetURLQueryParams'
GenerateIntelligentSearchURLRequest:
type: object
properties:
additional_query_params:
$ref: '#/components/schemas/IntelligentSearchQueryParams'
GenerateIntelligentSearchURLResponse:
type: object
properties:
operation_id:
type: string
enum:
- insights_v1_intelligent_search_url_post
data:
type: object
properties:
url:
type: string
format: uri
metadata:
type: object
properties:
sufficient_data:
type: boolean
GenerateAccountsURLRequest:
type: object
properties:
additional_query_params:
$ref: '#/components/schemas/SpendingAnalysisQueryParams'
GenerateAccountsURLResponse:
type: object
properties:
operation_id:
type: string
enum:
- insights_v1_accounts_url_post
data:
type: object
properties:
url:
type: string
format: uri
metadata:
type: object
properties:
sufficient_data:
type: boolean
parameters:
SmartFinderFrom:
in: header
name: X-From
required: false
schema:
type: string
examples:
date_only:
value: '2022-02-28'
RFC3339:
value: '2019-02-28T07:20:50.52Z'
description: Transaction from date, this works in pair with the 'X-To' parameter
SmartFinderTo:
in: header
name: X-To
required: false
schema:
type: string
examples:
date_only:
value: '2022-03-30'
RFC3339:
value: '2019-03-30T07:20:50.52Z'
description: Transaction to date, this works in pair with the 'X-From' parameter
HeaderSearchTransactionsAccept:
in: header
name: Accept
schema:
$ref: '#/components/schemas/TransactionsContentType'
required: false
description: The requested transaction format (e.g. full transaction model vs only IDs)
HeaderTimezone:
in: header
name: X-Timezone
schema:
type: string
format: tz database identifier
required: true
description: The [tz database identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) for the user's timezone.
examples:
Los Angeles, CA, USA:
value: US/Pacific
UK:
value: Europe/London
QueryUserInput:
name: user_input
in: query
schema:
type: string
maxLength: 512
required: false
QueryMerchantName:
name: merchant_name
in: query
schema:
type: string
maxLength: 512
required: false
QueryCategoryL1:
name: category_l1
in: query
schema:
type: string
maxLength: 512
required: false
QueryCategoryL2:
name: category_l2
in: query
schema:
type: string
maxLength: 512
required: false
QueryDescription:
name: description
in: query
schema:
type: string
maxLength: 512
required: false
QueryTag:
name: tag
in: query
schema:
type: string
maxLength: 512
required: false
QueryAccountId:
name: account_id
in: query
schema:
type: string
maxLength: 512
example: RxsYshVGded4JeilkXgWKdXA
required: false
description: |
Account id used to filter results. If multiple account ids are supplied, transactions from all of the supplied accounts will be included in results.
QueryCreditDebitIndicator:
name: credit_debit_indicator
in: query
schema:
type: string
enum:
- credit
- debit
required: false
QueryAmountMin:
name: amount_min
in: query
schema:
type: number
minimum: 0
required: false
description: |
Include transactions with an amount value greater than or equal to the specified value
QueryAmountMax:
name: amount_max
in: query
schema:
type: number
required: false
description: |
Include transactions with an amount value less than or equal to the specified value. Must be greater than 0.
PathSearchId:
in: path
name: search_id
schema:
type: string
format: uuid
example: 2f6c8ebe-b408-43f8-9152-80e2275deec5
required: true
QueryBudPageToken:
in: query
name: page_token
schema:
type: string
example: eyJoZWxsbyI6ICJ3b3JsZCJ9Cg==
description: Use this parameter to fetch a specific page of results. Provided by the next_page_token field in the previous request.
QueryBudPageSize:
in: query
name: page_size
schema:
type: integer
example: 25
description: Use this parameter to set the maximum number of results to be returned. This defaults to 25, and has a maximum of 100.
ClientId:
in: header
name: X-Client-Id
schema:
type: string
required: true
description: The API Client Identifier (Service Application Identifier).
example: 8711bbef-b357-4c2d-97ca-0d9df4206e9a
MetadataFieldName:
in: query
name: metadata.{field_name}
schema:
type: string
description: |
Search by exact-match on the `field_name` of `metadata` properties.
Example: `metadata.loan_product_code=credit_card_1234` will limit results to all
customer applications that have the following metadata contained:
```json
{
"metadata": {
"loan_product_code": "credit_card_1234"
}
}
```
PageToken:
in: query
name: page_token
schema:
type: string
description: |
Token provided in the `metadata` blob of a response, in order to find
the next page in a collection, e.g.
```json
{
"metadata": {
"next_page_token": "4jmBrvVn9r"
}
}
```
CustomerApplicationID:
in: path
name: application_id
required: true
schema:
$ref: '#/components/schemas/CustomerApplicationID'
BucketID:
in: path
name: bucket_id
required: true
description: |
ID of the bucket (whose criteria can be used to calculate totals).
schema:
anyOf:
- title: Fixed ID
type: string
description: |
Fixed IDs for buckets that are usable in any environment for particular
use-cases (e.g. `assess-dashboard` for the Assess Dashboard).
enum:
- assess-dashboard
- title: UUID
type: string
format: uuid
description: |
UUID of buckets that you have generated.
CategoryLookup:
in: query
name: category_lookup
description: |
Include to ensure that `category_lookup` is present in the `metadata` of the response.
allowEmptyValue: true
schema:
type: boolean
BucketLookup:
in: query
name: bucket_lookup
description: |
Include to ensure that `bucket_lookup` is present in the `metadata` of the response.
allowEmptyValue: true
schema:
type: boolean
UnbucketedCategories:
in: query
name: unbucketed_categories
description: |
Include to ensure that `unbucketed_categories` is present in the `metadata` of the response.
allowEmptyValue: true
schema:
type: boolean
GroupBy:
in: query
name: group_by
required: true
style: form
explode: false
description: |
Defines hierarchy of groupings for the resulting totals. For example:
```
group_by=bucket_l1,bucket_l2
```
Will result in getting groups by L1 buckets, then within those, their respective L2 buckets.
schema:
type: array
minItems: 1
items:
$ref: '#/components/schemas/GroupType'
uniqueItems: true
DateRangeEnd:
in: query
name: date_range_end
schema:
allOf:
- $ref: '#/components/schemas/DateRangeEnd'
- default: latest_calendar_month
DateRangeDurations:
in: query
name: date_range_durations
style: form
explode: false
description: |
Used with `timezone` and `date_range_end` to determine the list of `date_ranges` that appear in the
metadata of the response. Use this to configure the specific periods of time that you wish to assess
a customer's application data over.
schema:
type: array
default:
- P1M
- P3M
- P6M
- P12M
items:
$ref: '#/components/schemas/DayOrMonth'
RedirectURLCallbackApplicationID:
in: query
name: application_id
schema:
$ref: '#/components/schemas/CustomerApplicationID'
RedirectURLCallbackConnectionID:
in: query
name: connection_id
schema:
$ref: '#/components/schemas/ConnectionID'
RedirectURLCallbackStatus:
in: query
name: status
required: true
schema:
type: string
enum:
- success
- failure
- pending
RedirectURLCallbackCustomerID:
in: query
name: customer_id
description: |
Open Banking "Connect Completed" event customer ID. This is the `customer_id`
seen on the customer application under [Retrieve Customer Application](https://docs.thisisbud.com/reference/v1_customer_application_get).
schema:
type: string
format: uuid
RedirectURLCallbackTaskID:
in: query
name: task_id
description: |
Open Banking "Connect Completed" event task ID.
See [here](https://docs.thisisbud.com/docs/open-banking-connect-completed) for details.
schema:
type: string
format: uuid
RedirectURLCallbackError:
in: query
name: error
description: |
Error code indicating the status of the connection.
- `connection_expired` - link was accessed after expiry time
- `connection_already_started` - customer has already used the link to connect accounts
schema:
type: string
enum:
- connection_expired
- connection_already_started
OBProvidersQueryTypeFilter:
in: query
required: false
name: types
description: A comma separated list of Bud support provider types to be shown. If no filter is applied, all the providers are returned.
schema:
type: string
enum:
- sandbox
- business
- retail
OBProvidersQueryRegionFilter:
in: query
required: false
name: region
description: A comma separated list of Bud regions to be shown. If no filter is applied, all the providers are returned.
schema:
type: string
enum:
- GBR
OBProvidersQueryScopesFilter:
in: query
required: false
name: scopes
description: A comma separated list of Bud ob scopes to be shown. If no filter is applied, all the providers are returned.
schema:
type: string
enum:
- accounts
- balances
- transactions
- parties
- direct-debits
CustomerId:
in: header
name: X-Customer-Id
schema:
type: string
format: uuid
required: true
description: A unique identifier for a Customer, as registered on Bud's platform.
example: c3339af9-2426-44d4-9c4d-ddb8fd281e23
CustomerIdempotentIdentifier:
in: header
name: X-Customer-Idempotent-Identifier
schema:
type: string
description: |
Use the internal client identifier, provided in the `client_metadata` object when creating the customer in __Create Customer V3__, in place of an `X-Customer-Id` header.
CustomerSecret:
in: header
name: X-Customer-Secret
schema:
type: string
required: false
description: The Bud Customer secret used to encrypt customer data. This is required only if the customer secret is not already stored with Bud.
SignatureHeaderParameter:
in: header
name: X-Signature
description: The signed request body JWT
required: true
schema:
type: string
SigningIdHeaderParameter:
in: header
name: X-Signing-ID
description: The public key ID which should be used to verify the X-Signature header. Bud's list of public keys can be found at https://assets.thisisbud.com/bud-callback.jwks
required: true
schema:
type: string
TaskId:
in: path
name: task_id
schema:
type: string
format: uuid
required: true
description: Bud Task identifier returned from an async task for the requested action
ConnectionTaskId:
in: path
name: connection_task_id
schema:
type: string
format: uuid
required: true
description: Unique identifier related to a specific connection task
ConsentStatus:
in: query
name: status
schema:
type: string
enum:
- all
- active
- reconfirm_due
required: false
description: By default this endpoint only returns `active` Authorised connections. To retrieve `all` consents, add this query param with the value of `all`. To retrieve consents where reconfirmation is required add this query param with the value of `reconfirm_due`.
CustomerIPAddress:
in: header
name: X-Customer-Ip-Address
schema:
type: string
required: false
description: The Bud Customer IP Address is used for logging customer presence. This is optional and is only required for Agent of Bud clients.
ConsentId:
in: path
name: consent_id
schema:
type: string
required: true
description: Bud Consent identifier
IngestAccountsContentType:
in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/bud-accounts+json
description: Define the transactions' format for this request.
IngestTransactionsV2ContentType:
in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/bud-transaction-v3+json
- application/bud-transaction-v2+json
description: Define the transactions' format for this request.
DisableSynchronous:
in: header
name: X-Disable-Synchronous
description: |
If provided as true, the task will **not** be processed synchronously.
If false or the header is not included, the task **will** be processed synchronously.
schema:
type: boolean
GenerateTransactionIDs:
in: header
name: X-Generate-Transaction-IDs
schema:
type: string
enum:
- 'true'
example: 'true'
description: |
Enable transaction ID generation based on the contents of the transaction data. The transaction ID field still needs to be provided, but it will not be validated or checked for uniqueness and instead overwritten with a generated value.
When generating IDs from transaction data, the following fields are taken into account: account ID, description, amount, currency and date.
BudCategorisationModel:
in: header
name: X-Bud-Categorisation-Model
description: |
Overrides the default categorisation model for both the returned enrichment and the persisted enrichment.
Possible values can be retrieved from the __Retrieve Available Categorisation Models V2__ endpoint.
It should be noted that only models for the customers region will be used. For example, if a customer is created with the region "GB", then only "uk-v*" models will be utilised.
If a model is specified that cannot be used, then the default model will be used instead.
schema:
type: string
NoCustomerHeader:
in: header
name: X-No-Customer
schema:
type: boolean
description: |-
If provided as true, the customer_id is not required in the request. This is only available with X-Disable-Synchronous not set or set to false.
**Note:** This functionality is not available by default. In order to use it, please raise a Support request.
example: true
PathCustomerID:
in: path
name: customer_id
schema:
type: string
format: uuid
required: true
description: A unique identifier for a Customer, as registered on Bud's platform.
example: c3339af9-2426-44d4-9c4d-ddb8fd281e23
CategoryTotalsQueryFromTimestamp:
in: query
name: from
schema:
type: string
example: '2023-05-21T07:20:50.52Z'
description: |
The date from when results are to be retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Defaults to 6 months ago.
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
CategoryTotalsQueryToTimestamp:
in: query
name: to
schema:
type: string
example: '2023-06-21T07:20:50.52Z'
description: |
The date up to when results are to be retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Defaults to today.
Examples:
- `2023-03-17T17:29:51Z`
- `2023-03-17T17:29:51-08:00`
QueryBudCategory:
in: query
name: category
schema:
type: string
example: shopping
description: |
Use this parameter to filter the results on l1 categories to include.
Accepts multiple values, or values separated by comma.
To specify l2 categories to include, use the following format: `l1.l2`.
Examples:
- `shopping` - Filters the result set to only include data where the l1 category is `shopping`.
- `shopping.groceries` - Filters the result set to only include data where the l1 category is `shopping` and the l2 category is `groceries`.
QueryExcludeBudCategory:
in: query
name: exclude_category
schema:
type: string
example: shopping
description: |
Use this parameter to filter the results on l1 categories to exclude.
Accepts multiple values, or values separated by comma.
To specify l2 categories to exclude, use the following format: `l1.l2`.
Examples:
- `shopping` - Filters the result set to exclude data where the l1 category is `shopping`.
- `shopping.groceries` - Filters the result set to only exclude data where the l1 category is `shopping` and the l2 category is `groceries`.
QueryCurrency:
in: query
name: currency
schema:
type: string
example: GBP
description: Use this parameter to filter the results returned on the `currency` associated with each result. Multiple values are accepted. If this parameter is not provided then results of any `currency` will be returned.
QueryAccountID:
in: query
name: account_id
schema:
type: string
required: false
description: The account ID to retrieve data for.
CategoryTotalsQueryCategoryFilter:
in: query
name: category_label
schema:
type: string
example: essential
description: |
Filters the categories included in the category totals to just those with the label(s) specified by this parameter.
For the SOT on which categories have which filters see the Retrieve Categories endpoint.
MerchantsTotalsIncludeCategories:
in: header
name: X-Include-Categories
schema:
type: string
example: shopping,entertainment
description: Comma-separated list of transaction categories to include in the total
MerchantsTotalsExcludeCategories:
in: header
name: X-Exclude-Categories
schema:
type: string
example: bills,finances
description: Comma-separated list of transaction categories to exclude from the total
QueryProvider:
in: query
name: provider
schema:
type: string
example: BankOfBud
description: Use this parameter to filter the results returned on the `provider` associated with each result. Multiple values are accepted. If this parameter is not provided then results of any `provider` will be returned.
PathAccountID:
in: path
name: account_id
schema:
type: string
required: true
description: The account ID to retrieve data for.
QueryFromBudDate:
in: query
name: from
schema:
type: string
example: '2019-02-29T12:23:00Z'
description: |
The date from when results are to be retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
QueryToBudDate:
in: query
name: to
schema:
type: string
example: '2019-02-29T12:23:00Z'
description: |
The date up to when results are to be retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-03-17T17:29:51Z`
- `2023-03-17T17:29:51-08:00`
QueryDateField:
in: query
name: date-field
deprecated: true
schema:
type: string
example: date_time
description: |
Specifies which date field as returned from the `/financial/v2/transactions` endpoint should be used in the calculation of balance over time.
Currently supported values include (but are not necessarily limited to):
- `date_time`
- `posted_date_time`
Defaults to `date_time`.
OBProvider:
in: path
name: provider
schema:
type: string
required: true
description: Name of the provider (banking institution)
MerchantCorrectionSearchQuery:
in: path
name: merchant_query
schema:
type: string
minLength: 3
required: true
description: Merchant Name Query
QueryExcludeSource:
in: query
name: exclude_source
schema:
type: boolean
required: false
description: Toggle whether the endpoint returns the transaction used as part of the request
PathTransactionID:
in: path
name: transaction_id
schema:
type: string
format: uuid
required: true
description: A transaction identifier
QueryBudAccountID:
in: query
name: account_id
schema:
type: string
example: RxsYshVGded4JeilkXgWKdXA
description: |
Use this parameter to filter the results on data associated with the given account id.
Example: `RxsYshVGded4JeilkXgWKdXA`
QueryDay:
in: query
name: day
schema:
type: string
example: '2019-02-29T12:23:00Z'
description: |
The day for which results are to be retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
Examples:
- `2023-01-17T17:29:51Z`
- `2023-01-17T17:29:51-08:00`
PathSpendingBudgetID:
name: budget_id
in: path
schema:
type: string
required: true
description: |
The ID of the spending budget.
Example: `81a68821-dca6-4771-80d4-002c7fce412e`
example: 81a68821-dca6-4771-80d4-002c7fce412e
parameters-QueryBudPageToken:
in: query
name: page_token
schema:
type: string
example: b21055a9a9f46fc794a2e6855c65abd7e317181039fc6930daabac5822911d14a84895ecd947e2b5abdcb22e4fcc2c594e1f661dc63e34b9ba88760724047990896f7581a0786c2605dce19c6a9d80d1044f963b74fea0a929c0a4465a6e67378a74dce38ec5e26ae4cc804b62fd666d5df4cf2e7f524bd99e5523bc5d471768065c036dc0c73122705b280817fbbd7d9aa31f271d72cd3877d999dcb9a5b1c0be0c05
description: Use this paramater to fetch a specific page of results. Provided by the next_page_token field in the previous request.
parameters-QueryBudPageSize:
in: query
name: page_size
schema:
type: integer
example: 200
description: Use this parameter to set the maximum number of results to be returned. This defaults to 100, and has a maximum of 200.
PathSavingsGoalIDV2:
name: savings_goal_id
in: path
schema:
type: string
format: uuid
required: true
description: |
The ID of the savings goal.
Example: `81a68821-dca6-4771-80d4-002c7fce412e`
example: 81a68821-dca6-4771-80d4-002c7fce412e
FutureTransactionsMonthsProjection:
in: query
name: months
schema:
type: integer
default: 3
required: false
example: 6
description: To specify how many months we return the prediction for, the default is 3 months.
FutureTransactionsChangePercentage:
in: query
name: change_percentage[subcategory]
schema:
type: number
default: 2
required: false
description: To set a percentage value used in the calculation of the forecasted amount for the future transactions categorised with specific transaction subcategory; for example `change_percentage[loans]=2.0`. This can be a positive or negative float number. To apply the same percentage to all transactions use the `subcategory=all`.
QueryFromDate:
in: query
name: from
schema:
type: string
example: '2019-02-29'
description: 'Filter from this date (format: `YYYY-MM-DD`).'
QueryToDate:
in: query
name: to
schema:
type: string
example: '2019-02-29'
description: 'Filter to this date (format: `YYYY-MM-DD`).'
Timezone:
in: query
name: timezone
schema:
$ref: '#/components/schemas/TimezoneIdentifier'
DateFrom:
in: query
name: date_from
schema:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
DateTo:
in: query
name: date_to
schema:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
DeprecatedURLMonthFrom:
in: query
name: month_from
required: false
deprecated: true
description: |
Use `date_from` instead.
schema:
$ref: '#/components/schemas/schema'
DeprecatedURLMonthTo:
in: query
name: month_to
required: false
deprecated: true
description: |
Use `date_to` instead.
schema:
$ref: '#/components/schemas/URLMonthTo-schema'
URLMonthFrom:
in: query
name: month_from
required: false
schema:
type: string
example: 2019-02
description: Month (`YYYY-MM`) from which the transactions should be returned from, this works in pair with the `month_to` parameter.
URLMonthTo:
in: query
name: month_to
required: false
schema:
type: string
example: 2019-03
description: Month (`YYYY-MM`) from which the transactions should be returned to, this works in pair with the `month_from` parameter.
OverallTotals:
in: query
name: overall_totals
schema:
type: boolean
description: |
If `true`, shows the overall totals in the affordability report (under `overall_total` property).
MonthlyTotals:
in: query
name: monthly_totals
schema:
type: boolean
description: |
If `true`, shows the monthly totals in the affordability report (under `monthly_totals` property).
Criteria:
in: query
name: criteria
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AffordabilityCriteria'
EnabledInsightsIncomeExpenditure:
in: query
name: enabled_insights
required: false
schema:
type: string
description: A comma-separated list of insight types to check for. If not specified, a default list will be used, which may be added to over time.
enum:
- income-cash-withdrawal
- income-loan
- income-gambling
- income-debt
- income-essential-expenditure
- income-all-expenditure
From:
in: query
name: from
required: false
description: A start time to check financial data for insights from. Configures the earliest financial data which may be used to generate insights. If omitted, defaults to the start of the sixth complete month prior to the latest ingested financial data. Note that some insights will only be checked for complete months entirely between the `from` and `to` dates.
schema:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
To:
in: query
name: to
required: false
description: An end time to check financial data for insights up to. Configures the latest financial data which may be used to generate insights. If omitted, defaults to the date of the latest ingested financial data. Note that some insights will only be checked for complete months entirely between the `from` and `to` dates. Insights relating to potential future events, such as cannot_cover_bills, may forecast them up to a month after this point.
schema:
$ref: '#/components/schemas/schemas-DateTimeISO8601'
Currency:
in: query
name: currency
required: false
description: |
Used to limit the insight reports returned, to only those in the specified currency. The value should represent
a valid ISO currency code. an example would be "GBP" or "EUR".
Please refer to https://www.iso.org/iso-4217-currency-codes.html for more details.
schema:
type: string
TransactionReference:
in: path
required: true
name: reference
schema:
description: A unique reference used to identify a group of transactions in report for aggregation analysis
type: string
EnabledInsightsMerchants:
in: query
name: enabled_insights
required: false
schema:
type: string
description: A comma-separated list of insight types to check for. If not specified, a default list will be used, which may be added to over time.
enum:
- hcst-credit
EnabledInsightsBalanceOverdraft:
in: query
name: enabled_insights
required: false
schema:
type: string
description: A comma-separated list of insight types to check for. If not specified, a default list will be used, which may be added to over time.
enum:
- unauthorised-overdraft
EnabledInsightsIncomeHealth:
in: query
name: enabled_insights
required: false
schema:
type: string
description: A comma-separated list of insight types to check for. If not specified, a default list will be used, which may be added to over time.
enum:
- income-health
PaymentProviderRegionFilter:
in: query
name: country
description: Country filter as a comma separated list of country codes following the ISO 3166 alpha-3 code format.
example: GBR,DEU
schema:
type: string
PaymentProviderServiceFilter:
in: query
name: product
description: Product filter as a comma separated list of bud supported products
schema:
$ref: '#/components/schemas/PaymentServices'
PaymentProviderTypeFilter:
in: query
required: false
name: type
description: A comma separated list of Bud support provider types to be shown. If no filter is applied, all the providers are returned.
schema:
type: string
enum:
- sandbox
- business
- retail
PaymentIdHeader:
in: header
name: X-Payment-Id
required: false
description: Payment ID filter
example: 84470aa9-71a2-4da2-8fa4-660adbf2c9b2
schema:
type: string
PageNumber:
in: header
name: X-Page-Number
required: false
description: Page number filter
example: '1'
schema:
type: string
PaymentSenderProviders:
in: header
name: X-Sender-Providers
required: false
description: comma separated list of providers name filter
example: Lloyds,Nationwide
schema:
type: string
PaymentStatusCodes:
in: header
name: X-Status-Codes
required: false
description: comma separated list of status codes filter
example:
- CREATED
- SETTLED
schema:
type: array
items:
type: string
enum:
- CREATED
- AWAITING_AUTH
- AUTHENTICATED
- ACCEPTED
- FUNDS_CONFIRMED
- INITIATING
- SETTLED
- FAILED
PaymentDateFrom:
in: header
name: X-Date-From
description: Date from filter
example: '2020-06-01T15:00:00Z'
schema:
type: string
PaymentDateTo:
in: header
name: X-Date-To
description: Date to filter
example: '2020-06-01T15:00:00Z'
schema:
type: string
PaymentAmountFrom:
in: header
name: X-Amount-From
required: false
description: Amount from filter
example: '10.00'
schema:
type: string
PaymentAmountTo:
in: header
name: X-Amount-To
required: false
description: Amount to filter
example: '10000.00'
schema:
type: string
PaymentId:
in: path
name: payment_id
required: true
schema:
type: string
description: Bud Payment Identifier
BalancesEnabledInsights:
in: query
name: enabled_insights
required: false
schema:
type: string
description: A comma-separated list of insight types to check for. If not specified, a default list will be used, which may be added to over time.
example: in_overdraft
enum:
- cannot_cover_bills
- in_overdraft
- close_to_credit_limit
- low_balance
CloseToCreditLimitPercentageUtilisationThreshold:
in: query
name: close_to_credit_limit.percentage_utilisation_threshold
required: false
schema:
type: number
description: A minimum percentage utilisation of the credit limit for this insight to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
LowBalanceBalanceThreshold:
in: query
name: low_balance.balance_threshold
required: false
schema:
type: number
description: A balance threshold such that balances lower than this will trigger the low balance insight. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
BalancesInsightType:
in: path
name: type
required: true
schema:
type: string
description: A type of balances insight available on the platform.
example: in_overdraft
enum:
- cannot_cover_bills
- in_overdraft
- close_to_credit_limit
- low_balance
InsightID:
in: path
name: id
required: true
schema:
type: string
description: The insight ID to provide data for,
example: late_income_8789764a-df2f-4589-b550-00bcd0e9cb2c
IncomeEnabledInsights:
in: query
name: enabled_insights
required: false
schema:
type: string
description: A comma-separated list of insight types to check for. If not specified, a default list will be used, which may be added to over time.
example: late_income
enum:
- late_income
- regular_income_changed
- gambling_income
- pension_income
GamblingIncomeMinimumMonthlyThreshold:
in: query
name: gambling_income.minimum_monthly_threshold
required: false
schema:
type: number
description: A minimum absolute total of gambling income for the insight to trigger. Both `gambling_income.minimum_monthly_threshold` and `gambling_income.minimum_percentage_total_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
GamblingIncomeMinimumPercentageTotalThreshold:
in: query
name: gambling_income.minimum_percentage_total_threshold
required: false
schema:
type: number
description: A minimum percentage of all income that must be gambling income for the insight to trigger. Both `gambling_income.minimum_monthly_threshold` and `gambling_income.minimum_percentage_total_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
LateIncomeMinimumValueThreshold:
in: query
name: late_income.minimum_value_threshold
required: false
schema:
type: number
description: A minimum value of a late transaction in that transaction's currency for the insight to trigger. Both `late_income.minimum_value_threshold` and `late_income.minimum_days_late_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
LateIncomeMinimumDaysLateThreshold:
in: query
name: late_income.minimum_days_late_threshold
required: false
schema:
type: number
description: A minimum number of days late for a transaction to be for the insight to trigger. Both `late_income.minimum_value_threshold` and `late_income.minimum_days_late_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
PensionIncomeMinimumMonthlyThreshold:
in: query
name: pension_income.minimum_monthly_threshold
required: false
schema:
type: number
description: A minimum absolute total of pension income for the insight to trigger. Both `pension_income.minimum_monthly_threshold` and `pension_income.minimum_percentage_total_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
PensionIncomeMinimumPercentageTotalThreshold:
in: query
name: pension_income.minimum_percentage_total_threshold
required: false
schema:
type: number
description: A minimum percentage of all income that must be pension income for the insight to trigger.. Both `pension_income.minimum_monthly_threshold` and `pension_income.minimum_percentage_total_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
RegularIncomeChangedMinimumAbsoluteChangeThreshold:
in: query
name: regular_income_changed.minimum_absolute_change_threshold
required: false
schema:
type: number
description: A minimum absolute change between the previous and latest amounts of a regular payment for the insight to trigger. Both `regular_income_changed.minimum_absolute_change_threshold` and `regular_income_changed.minimum_percentage_change_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
RegularIncomeChangedMinimumPercentageChangeThreshold:
in: query
name: regular_income_changed.minimum_percentage_change_threshold
required: false
schema:
type: number
description: A minimum percentage change between the previous and latest amounts of a regular payment for the insight to trigger. Both `regular_income_changed.minimum_absolute_change_threshold` and `regular_income_changed.minimum_percentage_change_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
IncomeInsightType:
in: path
name: type
required: true
schema:
type: string
description: A type of income insight available on the platform.
example: late_income
enum:
- late_income
- regular_income_changed
- gambling_income
- pension_income
SpendingEnabledInsights:
in: query
name: enabled_insights
required: false
schema:
type: string
description: A comma-separated list of insight types to check for. If not specified, a default list will be used, which may be added to over time.
example: late_payment
enum:
- late_payment
- suspected_duplicate_charge
- regular_payment_changed
- new_insurance_expense
LatePaymentMinimumValueThreshold:
in: query
name: late_payment.minimum_value_threshold
required: false
schema:
type: number
description: A minimum value of a late transaction in that transaction's currency for the insight to trigger. Both `late_payment.minimum_value_threshold` and `late_payment.minimum_days_late_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
LatePaymentMinimumDaysLateThreshold:
in: query
name: late_payment.minimum_days_late_threshold
required: false
schema:
type: number
description: A minimum number of days late for a transaction to be for the insight to trigger. Both `late_payment.minimum_value_threshold` and `late_payment.minimum_days_late_threshold` must be met to trigger. If not specified, a configured value will be used.
RegularPaymentChangedMinimumAbsoluteChangeThreshold:
in: query
name: regular_payment_changed.minimum_absolute_change_threshold
required: false
schema:
type: number
description: A minimum absolute change between the previous and latest amounts of a regular payment for the insight to trigger. Both `regular_payment_changed.minimum_absolute_change_threshold` and `regular_payment_changed.minimum_percentage_change_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
RegularPaymentChangedMinimumPercentageChangeThreshold:
in: query
name: regular_payment_changed.minimum_percentage_change_threshold
required: false
schema:
type: number
description: A minimum percentage change between the previous and latest amounts of a regular payment for the insight to trigger. Both `regular_payment_changed.minimum_absolute_change_threshold` and `regular_payment_changed.minimum_percentage_change_threshold` must be met to trigger. If not specified, a configured value will be used. Please note that including this request on a customer level will increase latency of this endpoint. Instead, we recommend to update the thresholds for your organisation by raising a support request.
SpendingInsightType:
in: path
name: type
required: true
schema:
type: string
description: A type of spending insight available on the platform.
example: late_payment
enum:
- late_payment
- suspected_duplicate_charge
- regular_payment_changed
- new_insurance_expense
PathCustomInsightID:
in: path
name: custom_insight_id
required: true
schema:
type: string
format: uuid
responses:
SearchTransactionsResponse:
description: OK
headers:
Content-Type:
description: Defines the transactions' format for the response.
schema:
$ref: '#/components/schemas/TransactionsContentType'
content:
application/bud-transaction-v3+json:
schema:
$ref: '#/components/schemas/SearchTransactionsResponseBody'
example:
operation_id: search_beta_transactions_get
data:
id: 8a567b41-1b61-4f8f-a1ea-8fcb10d08d9f
results:
- matches:
- type: merchant_name
content: Dunkin'
- type: category_l2
content: coffee
transaction:
transaction_id: '378'
account_id: 5ce0749e-551c-4693-87f8-400d2551fdd1
provider: Chase
description: DUNKIN DONUTS COFFEE BROOKLYN NEW YORK
credit_debit_indicator: debit
amount:
value: '8.87'
currency: USD
date_time: '2025-03-02T00:00:00Z'
posted_date_time: '2025-03-02T00:00:00Z'
value_date_time: '2025-03-02T00:00:00Z'
status: booked
suggested_description: Dunkin'
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg
enrichments:
merchant:
id: ba8ef908-b624-4116-8b26-571e48d1bf4c
slug: dunkin
display_name: Dunkin'
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg
website: https://www.dunkindonuts.com
tokens:
- confidence: '1.00'
value: DUNKIN DONUTS COFFEE
categories:
l1:
slug: food_and_drink
confidence: '0.98'
l2:
slug: coffee
confidence: '0.96'
regularity:
frequency: biweekly
predicted_date_times:
- '2025-03-17T00:00:00Z'
- '2025-03-31T00:00:00Z'
- '2025-04-14T00:00:00Z'
- '2025-04-28T00:00:00Z'
- '2025-05-12T00:00:00Z'
- '2025-05-27T00:00:00Z'
- '2025-06-09T00:00:00Z'
- '2025-06-23T00:00:00Z'
group_label: 3e1b2ea4df1579fe9dcda6cf6b032492d8551e78404d023ca3d57ca8b1ae2159-4
location:
address:
city: New York
region: NY
country: US
geolocation:
longitude: -73.9872777778
latitude: 40.6919444444
tags:
- regular-transaction
- matches:
- type: merchant_name
content: Dunkin'
- type: category_l2
content: coffee
transaction:
transaction_id: '377'
account_id: 5ce0749e-551c-4693-87f8-400d2551fdd1
provider: Chase
description: DUNKIN DONUTS COFFEE BROOKLYN NEW YORK
credit_debit_indicator: debit
amount:
value: '6.54'
currency: USD
date_time: '2025-02-28T00:00:00Z'
posted_date_time: '2025-02-28T00:00:00Z'
value_date_time: '2025-02-28T00:00:00Z'
status: booked
suggested_description: Dunkin'
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg
enrichments:
merchant:
id: ba8ef908-b624-4116-8b26-571e48d1bf4c
slug: dunkin
display_name: Dunkin'
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg
website: https://www.dunkindonuts.com
tokens:
- confidence: '1.00'
value: DUNKIN DONUTS COFFEE
categories:
l1:
slug: food_and_drink
confidence: '0.98'
l2:
slug: coffee
confidence: '0.97'
regularity:
frequency: biweekly
predicted_date_times:
- '2025-03-14T00:00:00Z'
- '2025-03-28T00:00:00Z'
- '2025-04-11T00:00:00Z'
- '2025-04-25T00:00:00Z'
- '2025-05-09T00:00:00Z'
- '2025-05-23T00:00:00Z'
- '2025-06-06T00:00:00Z'
- '2025-06-20T00:00:00Z'
group_label: 3e1b2ea4df1579fe9dcda6cf6b032492d8551e78404d023ca3d57ca8b1ae2159-3
location:
address:
city: New York
region: NY
country: US
geolocation:
longitude: -73.9872777778
latitude: 40.6919444444
tags:
- regular-transaction
suggested_searches:
- filter:
type: merchant_name
value: Dunkin'
logo: https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png
url: /search/beta/transactions?merchant_name=Dunkin'
- filter:
type: category_l2
value: coffee
logo: https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png
url: /search/beta/transactions?category_l2=coffee
insight:
url: /search/beta/transactions/8a567b41-1b61-4f8f-a1ea-8fcb10d08d9f/insight
url_delay: 1500
metadata:
query:
user_input: Dunki
from: '2025-01-01T00:00:00Z'
to: '2025-02-01T00:00:00Z'
next_page_token: eyJoZWxsbyI6ICJ3b3JsZCJ9Cg==
results: 2
expires_in: 60
application/bud-transaction-id+json:
schema:
$ref: '#/components/schemas/SearchTransactionsResponseBodyTransactionId'
example:
operation_id: search_beta_transactions_get
data:
id: 8a567b41-1b61-4f8f-a1ea-8fcb10d08d9f
results:
- transaction_id: '378'
matches:
- type: merchant_name
content: Dunkin'
- type: category_l2
content: coffee
- transaction_id: '377'
matches:
- type: merchant_name
content: Dunkin'
- type: category_l2
content: coffee
suggested_searches:
- filter:
type: merchant_name
value: Dunkin'
logo: https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png
url: /search/beta/transactions?merchant_name=Dunkin'
- filter:
type: category_l2
value: coffee
logo: https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png
url: /search/beta/transactions?category_l2=coffee
insight:
url: /search/beta/transactions/8a567b41-1b61-4f8f-a1ea-8fcb10d08d9f/insight
url_delay: 1500
metadata:
query:
user_input: Dunki
from: '2025-01-01T00:00:00Z'
to: '2025-02-01T00:00:00Z'
next_page_token: eyJoZWxsbyI6ICJ3b3JsZCJ9Cg==
results: 2
expires_in: 60
SearchTransactionsInsightResponse:
description: OK
headers:
Retry-After:
schema:
type: integer
description: Time in milliseconds to wait before retrying.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchTransactionsInsightResponseBody'
examples:
pending:
value:
operation_id: search_beta_transactions_insight_get
data:
id: 234029b1-37ee-4942-b56d-5588f293f571
status: pending
metadata:
query:
user_input: Dunki
from: '2025-01-01T00:00:00Z'
to: '2025-02-01T00:00:00Z'
expires_in: 60
completed:
value:
operation_id: search_beta_transactions_insight_get
data:
id: 234029b1-37ee-4942-b56d-5588f293f571
status: completed
content:
text: You have spent $20 at Dunkin', this is up 50% of your coffee spend....
matched_searches:
- filter:
type: merchant
value: Dunkin'
logo: https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png
url: /search/beta/transactions?merchant=Dunkin'
text_positions:
- start: 22
end: 59
- filter:
type: category_l2
value: coffee
logo: https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png
url: /search/beta/transactions?category_l2=coffee
text_positions:
- start: 64
end: 70
transactions:
url: /search/beta/transactions/234029b1-37ee-4942-b56d-5588f293f571/insight/transactions
results: 10
merchants:
- display_name: Dunkin'
logo: https://assets.thisibud.com/5c97ffcf-9604-4fd9-bef1-1496ccce2d12.png
metadata:
query:
user_input: Dunki
from: '2025-01-01T00:00:00Z'
to: '2025-02-01T00:00:00Z'
expires_in: 60
SearchInsightTransactionsResponse:
description: OK
headers:
Content-Type:
description: Defines the transactions' format for the response.
schema:
$ref: '#/components/schemas/TransactionsContentType'
content:
application/bud-transaction-v3+json:
schema:
$ref: '#/components/schemas/SearchInsightTransactionsResponseBody'
example:
operation_id: search_beta_transactions_insight_transactions_get
data:
id: 8a567b41-1b61-4f8f-a1ea-8fcb10d08d9f
results:
- matches:
- type: merchant_name
content: Dunkin'
- type: category_l2
content: coffee
transaction:
transaction_id: '378'
account_id: 5ce0749e-551c-4693-87f8-400d2551fdd1
provider: Chase
description: DUNKIN DONUTS COFFEE BROOKLYN NEW YORK
credit_debit_indicator: debit
amount:
value: '8.87'
currency: USD
date_time: '2025-03-02T00:00:00Z'
posted_date_time: '2025-03-02T00:00:00Z'
value_date_time: '2025-03-02T00:00:00Z'
status: booked
suggested_description: Dunkin'
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg
enrichments:
merchant:
id: ba8ef908-b624-4116-8b26-571e48d1bf4c
slug: dunkin
display_name: Dunkin'
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg
website: https://www.dunkindonuts.com
tokens:
- confidence: '1.00'
value: DUNKIN DONUTS COFFEE
categories:
l1:
slug: food_and_drink
confidence: '0.98'
l2:
slug: coffee
confidence: '0.96'
regularity:
frequency: biweekly
predicted_date_times:
- '2025-03-17T00:00:00Z'
- '2025-03-31T00:00:00Z'
- '2025-04-14T00:00:00Z'
- '2025-04-28T00:00:00Z'
- '2025-05-12T00:00:00Z'
- '2025-05-27T00:00:00Z'
- '2025-06-09T00:00:00Z'
- '2025-06-23T00:00:00Z'
group_label: 3e1b2ea4df1579fe9dcda6cf6b032492d8551e78404d023ca3d57ca8b1ae2159-4
location:
address:
city: New York
region: NY
country: US
geolocation:
longitude: -73.9872777778
latitude: 40.6919444444
tags:
- regular-transaction
- matches:
- type: merchant_name
content: Dunkin'
- type: category_l2
content: coffee
transaction:
transaction_id: '377'
account_id: 5ce0749e-551c-4693-87f8-400d2551fdd1
provider: Chase
description: DUNKIN DONUTS COFFEE BROOKLYN NEW YORK
credit_debit_indicator: debit
amount:
value: '6.54'
currency: USD
date_time: '2025-02-28T00:00:00Z'
posted_date_time: '2025-02-28T00:00:00Z'
value_date_time: '2025-02-28T00:00:00Z'
status: booked
suggested_description: Dunkin'
suggested_logo: https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg
enrichments:
merchant:
id: ba8ef908-b624-4116-8b26-571e48d1bf4c
slug: dunkin
display_name: Dunkin'
logo: https://assets.thisisbud.com/datasci-images/merchant_logos/ba8ef908-b624-4116-8b26-571e48d1bf4c/v3/dunkin.jpeg
website: https://www.dunkindonuts.com
tokens:
- confidence: '1.00'
value: DUNKIN DONUTS COFFEE
categories:
l1:
slug: food_and_drink
confidence: '0.98'
l2:
slug: coffee
confidence: '0.97'
regularity:
frequency: biweekly
predicted_date_times:
- '2025-03-14T00:00:00Z'
- '2025-03-28T00:00:00Z'
- '2025-04-11T00:00:00Z'
- '2025-04-25T00:00:00Z'
- '2025-05-09T00:00:00Z'
- '2025-05-23T00:00:00Z'
- '2025-06-06T00:00:00Z'
- '2025-06-20T00:00:00Z'
group_label: 3e1b2ea4df1579fe9dcda6cf6b032492d8551e78404d023ca3d57ca8b1ae2159-3
location:
address:
city: New York
region: NY
country: US
geolocation:
longitude: -73.9872777778
latitude: 40.6919444444
tags:
- regular-transaction
metadata:
query:
user_input: Dunki
from: '2025-01-01T00:00:00Z'
to: '2025-02-01T00:00:00Z'
next_page_token: eyJoZWxsbyI6ICJ3b3JsZCJ9Cg==
expires_in: 60
application/bud-transaction-id+json:
schema:
$ref: '#/components/schemas/SearchInsightTransactionsResponseBodyTransactionId'
example:
operation_id: search_beta_transactions_insight_transactions_get
data:
id: 8a567b41-1b61-4f8f-a1ea-8fcb10d08d9f
results:
- transaction_id: '378'
matches:
- type: merchant_name
content: Dunkin'
- type: category_l2
content: coffee
- transaction_id: '377'
matches:
- type: merchant_name
content: Dunkin'
- type: category_l2
content: coffee
metadata:
query:
user_input: Dunki
from: '2025-01-01T00:00:00Z'
to: '2025-02-01T00:00:00Z'
next_page_token: eyJoZWxsbyI6ICJ3b3JsZCJ9Cg==
expires_in: 60
x-tagGroups:
- name: ''
tags:
- OAuth2
- Authentication
- name: ''
tags:
- Create a Connection
- Manage a Connection
- Ingest First Party Data
- Connect API
- name: ''
tags:
- Manage Customers
- Customers API
- name: ''
tags:
- Enrichment Resources
- Enrichment Totals
- Enrichment API
- name: ''
tags:
- Retrieve Financial Data
- Manage Financial Data
- Correct Financial Data
- Financial Data API
- name: ''
tags:
- Spending Budgets
- Savings Goals V2
- Goals API
- name: ''
tags:
- Regular Payments Finder
- Income Finder
- Loan Finder
- Debt Collection Finder
- Product Finder
- Subscription Finder
- Smart Finders API
- name: ''
tags:
- Transaction Search
- Intelligent Search API
- name: ''
tags:
- Customer Applications
- Customer Application Links
- Aggregation Buckets
- Retrieve Affordability Report V2
- Retrieve Affordability Report
- Retrieve Affordability Risk Insights
- Assess API
- name: ''
tags:
- Initiate Payment - Bud license
- Initiate Payment - Client license
- Manage Payments
- Payments API
- name: ''
tags:
- Retrieve Customer Characteristics
- Characteristics API
- name: ''
tags:
- Retrieve Actionable Insights
- Custom Insights
- Frontend Widgets
- Insights API