Bud Financial Enrichment Resources API

openapi: 3.2.0
info:
  title: 'Bud API Services: Documentation Enrichment Resources API'
  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,iVBORw0KGgoAAAANSUhEUgAAATAAAABuCAQAAAAKAYdLAAAACXBIWXMAAC4jAAAuIwF4pT92AAAAB3RJTUUH4wQDDggcbXcx7wAABeJJREFUeNrt3W2IFVUcx/HvXRW1VdQedy1bZVfoYX0osVQyfSGElKbRA5oFIaIlhAkWUYm6gvqqDMHMoBeKlhayCCZC2AMRPay7aJrSZmauZhQqaj7t7u1Fi965987s7D1n7pk7/j73zX2Y85//mXt2Zu45Z2ZBREREREREREREREREREREREREREREREREREREREREREREREREROIiZSFGH+YxgsOs5U/X1bFiPDPpQT3bu1DmcaZyg+vErWpjD+s47zoN6Mte0qRJc4Iq18lYMJv2jvosD11mRUeJpD32UO7664BFGQl94DoZY704fbU2rQwKVWYwbc6bQlSPBaYbtMz4K7nP53lpGkK/q8+7MTxUmeEWtmJcGX+j5psmM0I3l9vCirKAV36OuE46QsbfaHL/9opnL9tcpxBf3V0nkAgzWMRj9HadhrH+3Gk7pBqYDZdY3oXfnHE2gc1U2gyoQ6Rk+pKZdgOqgYnXF7TYDGe3gcWgW85QH9cJxMAVm8HsNrBqhhV1U9g33XUCzo1gsM1wdhtYio8ZWsytYdksFrpOwbGhbLYb0PavyLs5wA+c9v28lRa+Zzt/+y5RwwKqaOCdgCjZRvEit/A1a7jou8xwJjOMAb7D+ylqqCmw1imeZ0oCBrv7Mzp+/QofFTDCdZG13Jw3Wi1nOpbZT9+QGUziUkeZ3T49z+P4pqCRuCkhM1jjfMwwqsdG182rsAaWJs0JxuWJ9knGEq+EzODHjDLTcj5NsbjgwehwDazm6vyL5D2MG5i7booKdjE25917M57XhoxUG1hmJUsjrmWtlVl18ZQ2DeCyH6ycT7kpIJ+wuQWVeZJXI69HcpsXHDQN4LajtZIlkcbvzWqn9St1R3nPNIT93wzt/MSZPO+nqKA65699Nos5FdHmgZkMzHnvIj9zLm9+Q7jd0nqP8VtkdSqWNppYxT+u08g+yW8OnKRXw4ac08hnPUscyvjkw5AZXM4os9jzyY6sdZ3h5YC++jLm0lrASf50T5krzEn0QbOLbB8in2FvwKfNPJczCXd0hLV7wPPqL8bybt691//aWWfhkPo2681PjZPDbgP7lYZOl1nNJs9rW4elXD2zfkK8wIFOy2w1XuuWyOpTkuw2sHOhlqrzvIqu59gbuYEdIcqcjSyb65SLX5EHOepgrbuKtJ6nHNQtxtx0U5xM8DoXMkez7K5xM7Tp4iS4WOvszvss5feSP9Fvo5EVnDDfHGJfpd157Y48xFRGmfaEaWcu/qqYZxpCDcxcqR8Mg9xlGkANzNz+BDcx4zEJNTBzv5gPCSeXTvJtmM+3PJqIKdNj6GE3pJsG5mIwOMp1ptnABgd1sq+G7ebnXZncHCKjG3+M1zpLTzMz7AZ00cBG5pmlFb3JmkQTSpPd21HZbWD9Qy21zPPK/zricNH6+B7mvZFreTpEtAFWt0dpsnoWZreBVTG+kyVS1GVN4/vDd9lJVIRY5yzfPdPlrPHHdTwYItr1bkLcTia8M1qPM9F3yRRjcuaYprNmHxzyfNbQyQlnGTM47ynhndFan7WuCywLODz35I2sC9DCXheZHBNpsXvZmu1fkZXs5rjPnPzb8hyAzrIzINr9HOBIwNXat+ZcleS1hame1714izc55jNvbVDBtz7pyWuJuI15P/tnx1F0UwzsQpprO5nil2KIQSZbqcspnwp57+iu2MQT1mMmhNue/MMR3xfwMi8VYRhnmJqXP/MG1lZwyVNMy9l/FR4tf/mdvB553Uz2sXFn+n1YaGCNBZZr5mH25by7xzCb3PKrmM+lgmK1BV4hdc0+2g2zjq8m1wlAOY1dvqXGKep87oZYzUmDW3Vs8+myuIf6Am6AsiT0Nljp/CYl0Twaze9ZaaN3u5w5jAy5L2ylhe/4nAu+S1Qwl+oCsrjCV2wM2KXfwSPUcmPIGv9LPZ91Ye1TEnEb80ztNLE+Dv8MS0RERERERERERERERERERERERERERERERERERERERERERERERERs+Q/rhi5WauEgfQAAAABJRU5ErkJggg==
servers:
- url: https://api-sandbox.thisisbud.com
tags:
- name: Enrichment Resources
  x-displayName: Enrichment Resources
  description: Obtain greater context to Bud's enrichment services.
paths:
  /resources/v2/categories/models:
    get:
      tags:
      - Enrichment Resources
      summary: Retrieve Available Categorisation Models V2
      description: Retrieve the available Bud categorisation models.
      operationId: resources_v2_models_get
      security:
      - OAuth2: []
      parameters:
      - $ref: '#/components/parameters/ClientId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetModelsResponse'
              example:
                operation_id: resources_v2_models_get
                data:
                - name: uk-v2
                  description: 'A UK categorisation model. This model can be used for the following use cases: affordability assessments, collections assessments, affordability monitoring, customer engagement and product recommendations.'
        '400':
          description: The request contains an invalid payload.
        '401':
          description: Unauthorised request
        '405':
          description: An unexpected HTTP method was used
        5XX:
          description: An unexpected error occurred on the server side
  /resources/v2/categories:
    get:
      tags:
      - Enrichment Resources
      summary: Retrieve Categories V2
      description: Retrieve a list of primary and secondary categories supported by Bud's categorisation model.
      operationId: resources_v2_categories_get
      security:
      - OAuth2: []
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - in: query
        name: format
        schema:
          type: string
          enum:
          - map
          - flat
          default: flat
        description: "Determines if the response will be structured:\n  - As a flat object where all categories and subcategories are listed separately under different fields. See the example response `Flat Response`.\n  - As a map where all categories are listed as objects themselves with their respective subcategories listed in fields within the category objects. See the example response `Map Response`.\n"
      - in: query
        name: model
        schema:
          type: string
        description: 'The name of the model for which categories should be returned. See the *List Categorisation Models V2* endpoint for available model names.

          '
      - in: query
        name: label
        schema:
          type: string
        description: Filter out categories that do not have the specified label. If unset, endpoint will include all labels
        example: essential
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCategoriesV2Response'
              examples:
                Category List (flat):
                  value:
                    operation_id: resources_v2_categories_get
                    data:
                      categories:
                      - travel
                      - banking
                      subcategories:
                      - holiday_and_travel_expenses
                      - flights_and_airport_expenses
                      - other_travel
                      - bank_fees_and_currency_exchange
                      - other_banking
                      - cash_withdrawals
                      - refunds_and_reversals
                      - overdraft_fees
                      - unpaid_transactions
                    metadata:
                      model:
                        name: uk-v2
                        description: 'A UK categorisation model. This model can be used for the following use cases: affordability assessments, collections assessments, affordability monitoring, customer engagement and product recommendations.'
                Category Map:
                  value:
                    operation_id: resources_v2_categories_get
                    data:
                    - name: travel
                      subcategories:
                      - name: holiday_and_travel_expenses
                        labels:
                        - travel
                      - name: flights_and_airport_expenses
                      - name: other_travel
                      labels:
                      - nonessential
                    - name: banking
                      subcategories:
                      - name: bank_fees_and_currency_exchange
                        labels:
                        - essential
                      - name: other_banking
                        labels:
                        - nonessential
                      - name: cash_withdrawals
                        labels:
                        - nonessential
                      - name: interest
                        labels:
                        - essential
                      - name: refunds_and_reversals
                      - name: overdraft_fees
                        labels:
                        - essential
                      - name: unpaid_transactions
                        labels:
                        - essential
                    metadata:
                      model:
                        name: uk-v2
                        description: 'A UK categorisation model. This model can be used for the following use cases: affordability assessments, collections assessments, affordability monitoring, customer engagement and product recommendations.'
        '400':
          description: The request contains an invalid payload.
        '401':
          description: Unauthorised request
        '404':
          description: Model not found
        '405':
          description: An unexpected HTTP method was used
        5XX:
          description: An unexpected error occurred on the server side
components:
  parameters:
    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
  schemas:
    GetCategoriesV2Response:
      title: Categories Response
      type: object
      description: Expected response structure for the get categories endpoint.
      required:
      - operation_id
      - data
      - metadata
      properties:
        operation_id:
          $ref: '#/components/schemas/OperationId'
        data:
          oneOf:
          - $ref: '#/components/schemas/CategoriesFlat'
          - $ref: '#/components/schemas/CategoriesMap'
        metadata:
          type: object
          required:
          - model
          properties:
            model:
              $ref: '#/components/schemas/schemas-CategorisationModel'
    GetModelsResponse:
      title: Models Response
      required:
      - operation_id
      - data
      properties:
        operation_id:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/schemas-CategorisationModel'
    CategoriesFlat:
      title: Category List
      type: object
      description: A list of all the available categories and subcategories.
      properties:
        categories:
          type: array
          description: List of all the available categories.
          items:
            type: string
        subcategories:
          type: array
          description: List of all the available subcategories.
          items:
            type: string
    CategoriesMap:
      title: Category Map
      description: A map of all the available categories and respective subcategories
      type: array
      items:
        title: Category
        description: A single category and its respective subcategories.
        type: object
        properties:
          name:
            title: Category Name
            description: The name of the category.
            type: string
          labels:
            title: Labels
            description: 'Cross category labels used in our engage products, all subcategories will inherit the labels of their parents.


              You can use these labels to understand how certain category determinations are being made, such as if a category considered essential.

              '
            type: array
            example:
            - essential
            items:
              type: string
          subcategories:
            title: Subcategories
            description: The respective subcategories for the given category.
            type: array
            items:
              title: subcategory
              description: A subcategory that belongs to the given category.
              type: object
              properties:
                name:
                  title: Subcategory Name
                  description: The name of the subcategory.
                  type: string
                labels:
                  title: Labels
                  description: 'Cross category labels used in our engage products.


                    You can use these labels to understand how certain category determinations are being made, such as if a category considered essential.

                    '
                  type: array
                  example:
                  - essential
                  items:
                    type: string
    OperationId:
      title: Operation Id Field
      type: string
      description: A unique identifier/reference associated with a given endpoint/operation
    schemas-CategorisationModel:
      title: Categorisation Model
      type: object
      description: Bud categorisation model.
      required:
      - name
      - description
      properties:
        name:
          type: string
          description: Name of the model.
        description:
          type: string
          description: Description of the model & use-cases it provides.
        deprecated:
          type: boolean
          description: A flag to mark a particular model version as deprecated (this field is omitted if the model is not deprecated).
  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