Bud Financial Limited Product Finder API

openapi: 3.2.0
info:
  title: Thisisbud Product Finder API
  x-logo:
    url: data:image/png;base64,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
  version: '1.0'
  description: 'Operations tagged Product Finder across 2 of this provider''s published API definitions: thisisbud-openapi-openapi.yml, thisisbud-openapi-us-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-sandbox.thisisbud.com
- url: https://api-sandbox-us.thisisbud.com
tags:
- name: Product Finder
  x-displayName: Product Finder
  description: Find information regarding your customer's financial products.
paths:
  /insights/v2/products:
    get:
      tags:
      - Product Finder
      summary: Retrieve Financial Products V2
      description: 'Financial Products returns the finance oriented products and services that a customer uses.

        This endpoint generates data using a customer''s transaction history.


        Financial Products detects the following types of products and services:

        - Loans

        - Buy Now, Pay Later (BNPL)

        - Mortgages

        - Insurance products

        - Credit Cards

        - Private Pensions

        - Savings and Investments


        *Notes:*

        - If from and to parameters are not set, this endpoint will default to using transactions from the last six months.


        > 🚧 Limitations

        >

        > Financial Products are only identified from debit transactions.'
      operationId: insights_v2_products
      security:
      - OAuth2: []
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/CustomerId'
      - $ref: '#/components/parameters/CustomerIdempotentIdentifier'
      - $ref: '#/components/parameters/CustomerSecret'
      - $ref: '#/components/parameters/QueryFromDate'
      - $ref: '#/components/parameters/QueryToDate'
      responses:
        '200':
          description: OK - everything worked as expected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProductsResponseV2'
              example:
                operation_id: insights_v2_products
                data:
                - type:
                  - credit_card
                  merchant:
                    id: nationwidebuildingsociety
                    logo: https://assets.thisisbud.com/bud-datasci-images/merchant_logos/e121c7aa-a254-41bb-ad3e-33b988f791be/v1/nationwidebuildingsociety.jpeg
                    name: Nationwide Building Society
                  amount:
                    value: '0.03'
                    currency: GBP
                  period: unknown
                - type:
                  - insurance
                  merchant:
                    id: aviva
                    logo: https://assets.thisisbud.com/bud-datasci-images/merchant_logos/c50be401-7891-44c5-9fed-535080e77c57/v1/aviva.jpeg
                    name: Aviva
                  amount:
                    value: '59.99'
                    currency: GBP
                  period: monthly
                metadata:
                  from: '2022-09-03T11:28:22.00Z'
                  to: '2023-03-03T11:28:22.00Z'
                  results: 2
        '400':
          description: The request contains an invalid payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
              example:
                operation_id: insights_v2_products
                code_id: failed_validation
                message: Invalid request payload.
                errors:
                  from: 'invalid ''from'' date: ''7th March 2023'''
        '401':
          description: Unauthorised Request - the request was not authenticated or authorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
              example:
                operation_id: unknown
                code_id: unknown
                message: Unauthorised request
        '500':
          description: Server Error - an unexpected error occurred on the server side
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
              example:
                operation_id: unknown
                code_id: unknown
                message: 'An error occurred while processing your request. Get in touch with us and provide us your request id: 7ef63242-ba6d-4661-8014-f9eaa9cb2ad8'
    servers:
    - url: https://api-sandbox.thisisbud.com
components:
  schemas:
    BadRequestResponse:
      title: Bad Request Response
      type: object
      description: Expected response structure
      required:
      - operation_id
      - code_id
      - message
      - errors
      properties:
        operation_id:
          $ref: '#/components/schemas/OperationId'
        code_id:
          type: string
          description: A descriptive enough string that is linked to the reason for the error.
        message:
          type: string
        errors:
          anyOf:
          - $ref: '#/components/schemas/Error'
          - $ref: '#/components/schemas/Errors'
    ServerErrorResponse:
      title: Server Error Response
      type: object
      required:
      - operation_id
      - code_id
      - message
      properties:
        operation_id:
          $ref: '#/components/schemas/OperationId'
        code_id:
          type: string
          description: A descriptive enough string that is linked to the reason for the error.
        message:
          type: string
          description: An actual user friendly error message.
        errors:
          anyOf:
          - $ref: '#/components/schemas/Error'
          - $ref: '#/components/schemas/Errors'
    OperationId:
      title: Operation Id Field
      type: string
      description: A unique identifier/reference associated with a given endpoint/operation
    Errors:
      title: Array of Error Object
      description: Contains a list of error messages
      type: object
      additionalProperties:
        type: array
        items:
          type: string
    BudCurrency:
      title: Currency
      description: 'The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) of the monetary amount.


        Example: `GBP`

        '
      type: string
    Error:
      title: Error Object
      type:
      - object
      - 'null'
      description: Contains a field specific error message
      additionalProperties:
        type: string
    BudAmount:
      title: Standard Bud Amount
      type: object
      description: The monetary amount.
      required:
      - value
      - currency
      properties:
        value:
          $ref: '#/components/schemas/BudMonetaryValue'
        currency:
          $ref: '#/components/schemas/BudCurrency'
    BudDateRangeMetadata:
      title: Metadata
      type: object
      required:
      - from
      - to
      properties:
        from:
          type: string
          description: "The date from when results were retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).\nThis is either populated with the default value used when retrieving the results, or the user specified parameter.\n\nExamples:\n  - `2023-01-17T17:29:51Z`\n  - `2023-01-17T17:29:51-08:00`\n"
        to:
          type: string
          description: "The date up to when results were retrieved in the format [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).\nThis is either populated with the default value used when retrieving the results, or the user specified parameter.\n\nExamples:\n  - `2023-03-17T17:29:51Z`\n  - `2023-03-17T17:29:51-08:00`\n"
    GetProductsResponseV2:
      title: Retrieve Financial Products V2 Response Structure
      type: object
      required:
      - operation_id
      - metadata
      properties:
        operation_id:
          $ref: '#/components/schemas/OperationId'
        data:
          type: array
          items:
            title: Financial_Product
            description: A Financial Product that a customer uses.
            type: object
            required:
            - type
            - merchant
            - amount
            - period
            properties:
              type:
                title: Financial_Product_Type
                description: "A list of the types products and services identified for the given Financial Product. Potential values could be (but not limited to):\n  - `loan`\n  - `bnpl`\n  - `mortgage`\n  - `insurance`\n  - `credit_card`\n  - `private_pension`\n  - `savings_and_investment`\n"
                type: array
                items:
                  type: string
              merchant:
                title: Financial_Product_Merchant
                description: Details of the merchant providing the Financial Product.
                type: object
                required:
                - id
                - name
                - logo
                properties:
                  id:
                    type: string
                    description: A unique ID for the merchant.
                  name:
                    type: string
                    description: The merchant's name in a displayable format.
                  logo:
                    type: string
                    description: The merchant's logo image URL location.
              amount:
                $ref: '#/components/schemas/BudAmount'
              period:
                title: Transaction Period
                description: 'The period between each transaction for the given product. Possible values are:

                  - `daily` -  This product is charged once a day.

                  - `weekly` - This product is charged once a week.

                  - `biweekly` - This product is charged once every two weeks.

                  - `monthly` - This product is charged once a monthy.

                  - `quarterly` - This product is charged once a quater (every 3 months).

                  - `six_monthly` - product is charged every six months.

                  - `annually` - This product is charged once a year.

                  - `unknown` - It is unknown how frequently this product is charged.

                  '
                type: string
                enum:
                - daily
                - weekly
                - biweekly
                - monthly
                - quarterly
                - six_monthly
                - annually
                - unknown
        metadata:
          title: Metadata
          allOf:
          - $ref: '#/components/schemas/BudDateRangeMetadata'
          - type: object
            required:
            - results
            properties:
              results:
                type: number
                title: Results count
                description: Number of products returned.
    BudMonetaryValue:
      title: Monetary Value
      description: "The value of the monetary amount. The value is formatted with the number of decimal places for the respective currency. \n\nExample: `10.98`\n"
      type: string
  parameters:
    QueryToDate:
      in: query
      name: to
      schema:
        type: string
      example: '2019-02-29'
      description: 'Filter to this date (format: `YYYY-MM-DD`).'
    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
    CustomerIdempotentIdentifier:
      in: header
      name: X-Customer-Idempotent-Identifier
      schema:
        type: string
      description: 'Use the internal client identifier, provided in the `client_metadata` object when creating the customer in __Create Customer V3__, in place of an `X-Customer-Id` header.

        '
    QueryFromDate:
      in: query
      name: from
      schema:
        type: string
      example: '2019-02-29'
      description: 'Filter from this date (format: `YYYY-MM-DD`).'
    CustomerId:
      in: header
      name: X-Customer-Id
      schema:
        type: string
        format: uuid
      required: true
      description: A unique identifier for a Customer, as registered on Bud's platform.
      example: c3339af9-2426-44d4-9c4d-ddb8fd281e23
    CustomerSecret:
      in: header
      name: X-Customer-Secret
      schema:
        type: string
      required: false
      description: The Bud Customer secret used to encrypt customer data. This is required only if the customer secret is not already stored with Bud.
  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-refined-from:
- thisisbud-openapi-openapi.yml
- thisisbud-openapi-us-openapi.yml
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