Bud API Services: Documentation (1.6.1)

Download OpenAPI specification:Download

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. You will be provided with access to the Bud Developer Console where you can create the API Credentials required to obtain an OAuth2 access token.

If you have any questions, please use our Support Center or email us on [email protected].

Bud Platform Products

Product Description
Open Banking Aggregation Simplified and unified access to Open Banking APIs
Investment & Pension Aggregation Unified access to Investment, Wealth, Credit and Pension Providers APIs
Categorisation as a Service Tag transactions with high level and low level categories to organise spending, automatically pick out key information and group spending amounts
Merchant Identification Identify top merchants, to enrich transactions with more information, like logos, and provide more relevant services based on merchant spending
Regular Transactions Automatic identification of regular incoming and outgoing transactions. Helps customers and clients understand monthly and quarterly spending and build features like Left to Spend
Significant Transactions Make customer journeys smarter by identifying, verifying and pre-filling key information
Affordability Breakdown your customer's income and spending by customisable groupings based on Bud's enrichments to inform affordability calculations
Rent Recognition Unlock credit for tenants by combining our rent finder, landlord verification and rent profile services with approved credit reference partners. Developed in conjunction with HM Treasury
Utility Switching Stop customers over paying on energy bills by finding their energy bill and comparing the market for a better deal
Mortgages Give customers a quick understanding of how much they can afford to borrow towards their new home
Home Insurance Empower customers to avoid the loyalty penalty by being able to quickly check how much they can be paying on home contents insurance
Broadband Give customers quick access to quotes: broadband, tv, landline apllicable to their home address
Payments Initiate payments from a range of supported providers using Bud's PIS APIs

Environments and API Base URIs

Bud currently supports two environments on its platform:

  1. Bud’s Sandbox Environment - https://api-sandbox.thisisbud.com/

  2. Bud’s Production Environment - 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.

Once you’ve completed the signup and activation process you will be able to create a new project in the Developer Console 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 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. 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 principles. Standard HTTP verbs and status codes are used for requests and response statuses. Request and response payloads are JSON 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 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 of the 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-Customer-Secret Customer Secret value necessary for authorisation to retrieve and decrypt the Customer Data stored in Bud platform
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}.

{
  "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.

{
  "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.

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.

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

Authentication

OAuth2

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 or X-Customer-Id and X-Customer-Secret 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"
    }
}
Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: /v1/oauth/token
Scopes:

    Customers API

    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.

    Manage Customers

    Manage the number of customers registered onto the Bud platform.

    Create Customer

    This endpoint is used to create a new Customer in order for them to consume the Bud services.

    Authorizations:
    header Parameters
    X-Client-Id
    required
    string

    The API Client Identifier (Service Application Identifier).

    Responses

    201

    The resource has been successfully created.