Bud Goals and Budgets API
Manage savings goals (V2) and spending budgets (V1) for end customers. Create, retrieve, list, and delete goals, attach contributing transactions to a budget, and track progress against a target amount and time horizon.
OpenAPI Specification
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 [[email protected]](mailto:[email protected]).
## 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": "[email protected]",
"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:<br>__POST__`/v1/open-banking/authorisation-url` (Request Payload)<br> __POST__`/v1/open-banking/connect/{connection_task_id}` (Response Payload)<br> __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)
# --- truncated at 32 KB (1262 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bud-co/refs/heads/main/openapi/bud-platform-openapi.yml