Bud Financial 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.'
  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:
  schemas:
    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).

                '
    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.
    ConnectionID:
      title: Connection ID
      type: string
      format: uuid
      description: 'The unique identifier for a customer application''s link (for connecting accounts).

        '
    OperationId:
      title: Operation Id Field
      type: string
      description: A unique identifier/reference associated with a given endpoint/operation
    CustomerApplicationID:
      title: Customer Application ID
      type: string
      format: uuid
      description: 'The unique identifier for a customer application.

        '
  parameters:
    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
    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'
    RedirectURLCallbackApplicationID:
      in: query
      name: application_id
      schema:
        $ref: '#/components/schemas/CustomerApplicationID'
    CustomerApplicationID:
      in: path
      name: application_id
      required: true
      schema:
        $ref: '#/components/schemas/CustomerApplicationID'
    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.\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
  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
  - 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