Bud Financial Limited Customer Application Links API

openapi: 3.2.0
info:
  title: 'Bud API Services: Documentation Customer Application Links…'
  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. 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 Centre or email us on 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/


    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.'
  contact:
    name: Bud Support
    email: help@thisisbud.com
    url: https://www.thisisbud.com/
  x-logo:
    url: data:image/png;base64,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
servers:
- url: https://api-sandbox.thisisbud.com
tags:
- 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.'
paths:
  /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.
components:
  parameters:
    CustomerApplicationID:
      in: path
      name: application_id
      required: true
      schema:
        $ref: '#/components/schemas/CustomerApplicationID'
    RedirectURLCallbackApplicationID:
      in: query
      name: application_id
      schema:
        $ref: '#/components/schemas/CustomerApplicationID'
    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
    RedirectURLCallbackConnectionID:
      in: query
      name: connection_id
      schema:
        $ref: '#/components/schemas/ConnectionID'
    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
    RedirectURLCallbackError:
      in: query
      name: error
      description: "Error code indicating the status of the connection.\n\n  - `connection_expired` - link was accessed after expiry time\n  - `connection_already_started` - customer has already used the link to connect accounts\n"
      schema:
        type: string
        enum:
        - connection_expired
        - connection_already_started
    RedirectURLCallbackStatus:
      in: query
      name: status
      required: true
      schema:
        type: string
        enum:
        - success
        - failure
        - pending
    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
  schemas:
    OperationId:
      title: Operation Id Field
      type: string
      description: A unique identifier/reference associated with a given endpoint/operation
    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).

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

        '
    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.
  securitySchemes:
    Basic:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /v1/oauth/token
          scopes: {}
      description: "\nAuthentication flow:\n\n1. Perform OAuth2 Client Credentials authentication using API Credentials (`client_id`,`client_secret`) to obtain an `access_token` against `/v1/oauth/token` endpoint,\n2. Use `access_token` as Bearer Authorisation for every other API request,\n3. Include `X-Client-Id` (=client_id) within the header of every API request,\n4. Note that some of the requests may also require `X-Customer-Id` to be provided within the request header.\n\n### Examples\nObtain OAuth2 `access_token` and `refresh_token` using `grant_type=client_credentials` and HTTP Basic auth header\n\n```\ncurl --basic --user {{client_id}}:{{client_secret}} \\\n  -X POST https://api-sandbox.thisisbud.com/v1/oauth/token \\\n  -H 'Content-Type: application/x-www-form-urlencoded' \\\n  -d grant_type=client_credentials\n```\n\nSuccessful response:\n```\n{\n  \"operation_id\": \"oauth_token_post\",\n  \"data\": {\n    \"access_token\": \"dd0c17e3fd6d2ce94aa091257a3ea393b4f9b5cf3d3e998f07dc9826da86ff15\",\n    \"token_type\": \"bearer\",\n    \"expires_in\": 3600,\n    \"refresh_token\": \"fac32cca7559d9f6e8f1dfe9a99c71fa1dcfeb482bedf287d7934d2667ae54b3\"\n  }\n}\n```\n\nRefresh `access_token` token using `refresh_token` against `/v1/oauth/token` endpoint with `grant_type=refresh_token`\n\n```\ncurl -X POST \\\n  https://api-sandbox.thisisbud.com/v1/oauth/token \\\n  -H 'Content-Type: application/x-www-form-urlencoded' \\\n  -H 'X-Client-Id: {{client_id}}' \\\n  -d 'grant_type=refresh_token&refresh_token={{refresh_token}}'\n```\n\nSuccessful response:\n```\n{\n    \"operation_id\": \"oauth_token_post\",\n    \"data\": {\n        \"access_token\": \"cc0c17e3fd6d2ce94aa091257a3ea393b4f9b5cf3d3e998f07dc9826da86ff94\",\n        \"token_type\": \"bearer\",\n        \"expires_in\": 3600,\n        \"refresh_token\": \"ffc30cca7559d9f6e8f1dfe9a99c71fa1dcfeb482bedf287d7934d2667ae54b3\"\n    }\n}\n```\n"
x-tagGroups:
- name: ''
  tags:
  - OAuth2
  - Client Secrets
  - 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
  - Manage Transaction Labels
  - 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