Bud API Services: Documentation (1.2.5)

Download OpenAPI specification:Download

Welcome to Bud's API Services!

Below, you will find information regarding terminology, response styling and error handling.

Glossary

  • client: An institution who has ownership of a group of customers who will access the Bud services. E.g. a bank or mobile application (Bud Application).
  • customer: A customer is an end user who has access to Bud services through client access credentials. E.g. a bank customer.
  • task: A task is an asynchronous background process that fulfils the request sent by client.

Response Styling

All the responses will contain (where applies) JSON formated data.

Success

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 have 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
errors Contains any relevant error information An optional JSON object

Examples

201 Created

After creating a new resource with POST /resources.

{
  "operation_id": "resources_post",
  "data": {
    "id": "111-AAA-222-BBB"
  },
  "metadata": {},
  "errors": {}
}

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"
  },
  "metadata": {},
  "errors": {}
}

Client Errors

The description and the listed status codes below indicate 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.

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

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

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 Errors

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.

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:

    Customer API

    The Customer API is a restful 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.

    Customers

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

    Request Body schema: application/json
    consent_given
    required
    string
    Enum: "true" "false"

    A flag to provide evidence that the Customer has given their consent to use a Bud service

    names
    Array of strings

    An optional array of names that will be removed (tokenised) from transaction descriptions in the event that Bud hold any transactional data on the Customer

    Responses

    201

    The resource has been successfully created.

    400

    The request contains an invalid payload.

    401

    An unauthenticated request was received.

    405

    The request uses an unexpected HTTP method.

    5XX

    An unexpected error occurred on the server side.

    post /v1/customers
    https://api-sandbox.thisisbud.com/v1/customers

    Request samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "consent_given": "true",
    • "names":
      [
      ]
    }

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "operation_id": "customers_create",
    • "data":
      {
      }
    }

    Remove Customer

    This endpoint is used to delete an existing Customer.

    Authorizations:
    path Parameters
    customer_id
    required
    string

    The resource identifier.

    header Parameters
    X-Client-Id
    required
    string

    The API Client Identifier (Service Application Identifier).

    Responses

    204

    The request was successfully processed and no content is returned.

    401

    An unauthenticated request was received.

    404

    The resource was not found.

    405

    The request uses an unexpected HTTP method.

    5XX

    An unexpected error occurred on the server side.

    delete /v1/customers/{customer_id}
    https://api-sandbox.thisisbud.com/v1/customers/{customer_id}

    Account Aggregation API

    This service handles connections to Open Banking institutions via Bud. Bud manages these connections as an Account Information Service Provider (AISP). The majority of the calls within this service are asynchronous, as such they follow a pattern of sending a request, responding with a task ID. This task ID can then be tracked, allowing for a more effecient, cross network implementation.

    Open Banking

    Get the list of banks

    This endpoint is used to get the list of providers available via Open Banking APIs.

    Authorizations:
    header Parameters
    X-Client-Id
    required
    string

    The API Client Identifier (Service Application Identifier).

    Responses

    200

    List of providers available via Open Banking APIs

    400

    Bad Request that fails validations on headers & payload

    401

    Unauthorized (BearerToken in 'Authorization' header fails the authentication)

    5XX

    An unexpected error occurred on the server side

    get /v1/banks
    https://api-sandbox.thisisbud.com/v1/banks

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {}

    Initiate Provider Authorisation

    Asynchronous task to request a new Open Banking authorisation url for a specific Customer and Bank.

    Authorizations:
    header Parameters
    X-Client-Id
    required
    string

    The API Client Identifier (Service Application Identifier).

    X-Customer-Id
    required
    string <uuid>

    Bud Customer identifier

    X-Customer-Secret
    required
    string

    Bud Customer secret

    Request Body schema: application/json
    bank_name
    required
    string

    A string that defines which bank the Customer is requesting the authorisation URL for

    Responses

    102

    An identical request has been accepted for processing but has not yet been completed

    202

    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

    400

    The request contains an invalid payload

    405

    The request uses an unexpected HTTP method

    5XX

    An unexpected error occurred on the server side

    post /v1/open-banking/authorisation-url
    https://api-sandbox.thisisbud.com/v1/open-banking/authorisation-url

    Request samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "bank_name": "Barclays"
    }

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "operation_id": "open_banking_authorise",
    • "data":
      {
      },
    • "metadata":
      {
      }
    }

    Retrieve Authorisation URL

    Get the authorisation URL for a specific asynchronous task. If the task is not yet completed, the data element will be null.

    Once the customer has successfully authenticated with the ASPSP, Bud will create a task to fetch the relevant data from the ASPSP The task id created will be passed back withint the registered client re-direct url. Please refer to the Check Connection Status endpoint for updates on this fetching process using the task id provided in the call back URL.

    Authorizations:
    path Parameters
    task_id
    required
    string <uuid>

    Bud Task identifier

    header Parameters
    X-Client-Id
    required
    string

    The API Client Identifier (Service Application Identifier).

    X-Customer-Id
    required
    string <uuid>

    Bud Customer identifier

    X-Customer-Secret
    required
    string

    Bud Customer secret

    Responses

    200

    The request was successful processed and the task has completed

    400

    The request contains an invalid payload

    405

    The request uses an unexpected HTTP method

    5XX

    An unexpected error occurred on the server side

    get /v1/open-banking/authorisation-url/{task_id}
    https://api-sandbox.thisisbud.com/v1/open-banking/authorisation-url/{task_id}

    Response samples

    Content type
    application/json
    Example
    Copy
    Expand all Collapse all
    {}

    Initiate Provider Connection Deprecated

    Asynchronous task to request the connection of a Customer's bank account. This requires an authorisation code, which is obtained when the Customer logs into their account via the Open Banking authentication URL.

    Please note, this endpoint is now deprecated and its functionality made redundant by an automated process that will begin fetching data from a relevant ASPSP once the customer as successfully authenticated with the ASPSP.

    Authorizations:
    header Parameters
    X-Client-Id
    required
    string

    The API Client Identifier (Service Application Identifier).

    X-Customer-Id
    required
    string <uuid>

    Bud Customer identifier

    X-Customer-Secret
    required
    string

    Bud Customer secret

    Request Body schema: application/json
    bank_name
    required
    string

    A string that defines which bank the Customer is requesting the authorisation URL for

    code
    required
    string

    The Customer's bank authorisation code.

    from
    integer

    The datetime (ISO 8601) defining when the Customer's data needs to be collected from

    Responses

    102

    An identical request has been accepted for processing but the processing has not been completed yet

    202

    A new Task has been generated to request the Customer's bank account connection. The generated task_id can be used to check the Task's status.

    400

    The request contains an invalid payload

    405

    The request uses an unexpected HTTP method

    5XX

    An unexpected error occurred on the server side

    post /v1/open-banking/connect
    https://api-sandbox.thisisbud.com/v1/open-banking/connect

    Request samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "bank_name": "Barclays",
    • "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    • "from": "2019-03-01T00:00:00+00:00"
    }

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "operation_id": "open_banking_connect",
    • "data":
      {
      },
    • "metadata":
      {
      }
    }

    Check Connection Status

    Get the status of an account connetion fo