> ## Documentation Index
> Fetch the complete documentation index at: https://help.mytruv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Transactions

> Get bank transactions across all connected accounts (v2, ClickHouse-backed).

Returns transactions within the specified date range from all linked bank accounts.
Reads from ClickHouse instead of Core API for improved performance.
Supports pagination, category/type/account/amount/merchant filtering, and sorting.

The ``daily_totals`` array in the response reflects the same active filters.
When ``transaction_type=DEBIT`` is applied, all daily net totals will be negative
(debits only, no credits to offset them) — this is intentional and arithmetically consistent.



## OpenAPI

````yaml GET /v2/users/transactions
openapi: 3.1.0
info:
  title: Truv Public API
  description: >
    Read-only API for personal access token (PAT) users.


    ## Authentication


    Authenticate with `Authorization: Bearer <token>`. Tokens have a `pat_`
    prefix

    and are generated in the Truv web app under Settings → API keys.


    ## Available Endpoints


    This API exposes a subset of read-only endpoints for retrieving financial
    data,

    account links, and user profile information.
  version: 1.0.0
servers:
  - url: https://api.mytruv.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: users
    description: User profile — read-only access to the authenticated user's profile.
  - name: financial-data
    description: >-
      Financial data — balances, transactions, income, spending, liabilities,
      and balance history.
  - name: links
    description: >-
      Account links — list connected financial institutions and payroll
      providers.
paths:
  /v2/users/transactions:
    get:
      tags:
        - financial-data
      summary: Get User Bank Transactions V2
      description: >-
        Get bank transactions across all connected accounts (v2,
        ClickHouse-backed).


        Returns transactions within the specified date range from all linked
        bank accounts.

        Reads from ClickHouse instead of Core API for improved performance.

        Supports pagination, category/type/account/amount/merchant filtering,
        and sorting.


        The ``daily_totals`` array in the response reflects the same active
        filters.

        When ``transaction_type=DEBIT`` is applied, all daily net totals will be
        negative

        (debits only, no credits to offset them) — this is intentional and
        arithmetically consistent.
      operationId: listTransactionsV2
      parameters:
        - name: transacted_at_from
          in: query
          required: true
          schema:
            type: string
            description: Start date for the transaction window (inclusive, YYYY-MM-DD).
            examples:
              - '2025-01-01'
            title: Transacted At From
          description: Start date for the transaction window (inclusive, YYYY-MM-DD).
        - name: transacted_at_to
          in: query
          required: false
          schema:
            type: string
            description: >-
              End date for the transaction window (inclusive, YYYY-MM-DD).
              Defaults to today.
            examples:
              - '2025-12-31'
            title: Transacted At To
          description: >-
            End date for the transaction window (inclusive, YYYY-MM-DD).
            Defaults to today.
        - name: categories
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 1000
              - type: 'null'
            description: >-
              Comma-separated category slugs to include (e.g.
              'income,transfer'). Omit to include all categories.
            examples:
              - income,transfer
            title: Categories
          description: >-
            Comma-separated category slugs to include (e.g. 'income,transfer').
            Omit to include all categories.
        - name: transaction_type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - DEBIT
                  - CREDIT
                type: string
              - type: 'null'
            description: >-
              Filter by transaction type. Omit to include both debits and
              credits.
            examples:
              - DEBIT
            title: Transaction Type
          description: Filter by transaction type. Omit to include both debits and credits.
        - name: account_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Comma-separated account IDs to include. Omit to include all
              accounts.
            examples:
              - acc_001,acc_002
            title: Account Ids
          description: >-
            Comma-separated account IDs to include. Omit to include all
            accounts.
        - name: min_amount
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: string
                pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              - type: 'null'
            description: Minimum transaction amount (absolute value). Inclusive.
            examples:
              - '10.00'
            title: Min Amount
          description: Minimum transaction amount (absolute value). Inclusive.
        - name: max_amount
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: string
                pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              - type: 'null'
            description: Maximum transaction amount (absolute value). Inclusive.
            examples:
              - '500.00'
            title: Max Amount
          description: Maximum transaction amount (absolute value). Inclusive.
        - name: merchant
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Case-insensitive substring match on merchant name or description.
            examples:
              - starbucks
            title: Merchant
          description: Case-insensitive substring match on merchant name or description.
        - name: exclude_categories
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 1000
              - type: 'null'
            description: >-
              Comma-separated category slugs to exclude (e.g.
              'transfer,uncategorized').
            title: Exclude Categories
          description: >-
            Comma-separated category slugs to exclude (e.g.
            'transfer,uncategorized').
        - name: sort_by
          in: query
          required: false
          schema:
            enum:
              - date
              - amount
            type: string
            description: Sort transactions by date or absolute amount.
            examples:
              - date
            default: date
            title: Sort By
          description: Sort transactions by date or absolute amount.
        - name: sort_order
          in: query
          required: false
          schema:
            enum:
              - asc
              - desc
            type: string
            description: 'Sort direction: ascending or descending.'
            examples:
              - desc
            default: desc
            title: Sort Order
          description: 'Sort direction: ascending or descending.'
        - name: page
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            description: >-
              1-based page number, defaulting to 1 when paginating. Pagination
              is off unless page or page_size is set; with neither set, all
              matching transactions are returned in one response.
            examples:
              - 1
            title: Page
          description: >-
            1-based page number, defaulting to 1 when paginating. Pagination is
            off unless page or page_size is set; with neither set, all matching
            transactions are returned in one response.
        - name: page_size
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 500
                minimum: 10
              - type: 'null'
            description: >-
              Transactions per page (min 10, max 500), defaulting to 500 when
              paginating. Pagination is off unless page or page_size is set;
              with neither set, all matching transactions are returned in one
              response.
            examples:
              - 100
            title: Page Size
          description: >-
            Transactions per page (min 10, max 500), defaulting to 500 when
            paginating. Pagination is off unless page or page_size is set; with
            neither set, all matching transactions are returned in one response.
        - name: include_hidden
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Include user-hidden transactions alongside visible ones. Hidden
              transactions can be unhidden; permanently deleted transactions are
              never returned regardless.
            examples:
              - true
            default: false
            title: Include Hidden
          description: >-
            Include user-hidden transactions alongside visible ones. Hidden
            transactions can be unhidden; permanently deleted transactions are
            never returned regardless.
      responses:
        '200':
          description: Paginated bank transactions (v2, ClickHouse-backed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionsReport'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BankTransactionsReport:
      properties:
        count:
          type: integer
          title: Count
        accounts:
          items:
            $ref: '#/components/schemas/Account1'
          type: array
          title: Accounts
        transactions:
          items:
            $ref: '#/components/schemas/Transaction1'
          type: array
          title: Transactions
        daily_totals:
          items:
            $ref: '#/components/schemas/DailyTotal'
          type: array
          title: Daily Totals
        merchant_logos:
          additionalProperties:
            anyOf:
              - type: string
              - type: 'null'
          type: object
          title: Merchant Logos
        next:
          anyOf:
            - type: string
            - type: 'null'
          title: Next
        previous:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous
      type: object
      required:
        - count
        - accounts
        - transactions
      title: BankTransactionsReport
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Account1:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          examples:
            - 24d7e80942ce4ad58a93f70ce4115f5c
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          examples:
            - '2022-05-04T11:30:00Z'
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          examples:
            - '2022-05-04T12:00:00Z'
        type:
          $ref: '#/components/schemas/Type4'
          examples:
            - CHECKING
        subtype:
          anyOf:
            - $ref: '#/components/schemas/Subtype1'
            - type: 'null'
          examples:
            - MONEY_MARKET
        mask:
          anyOf:
            - type: string
            - type: 'null'
          title: Mask
          examples:
            - '6789'
        nickname:
          anyOf:
            - type: string
            - type: 'null'
          title: Nickname
          examples:
            - My account
        balances:
          $ref: '#/components/schemas/AccountBalances'
      additionalProperties: true
      type: object
      required:
        - type
        - balances
      title: Account1
    Transaction1:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          examples:
            - 24d7e80942ce4ad58a93f70ce4115f5c
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          examples:
            - '2022-05-04T11:30:00Z'
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          examples:
            - '2022-05-04T12:00:00Z'
        account_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Id
          examples:
            - 68a7e80942ce4ad58a93f70ce411549a
        external_id:
          type: string
          title: External Id
          examples:
            - external_key_243901
        amount:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Amount
          examples:
            - '100.00'
        currency_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency Code
          examples:
            - USD
        check_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Check Number
          examples:
            - '123456'
        categories:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Categories
          examples:
            - - Transfer
        description:
          type: string
          title: Description
          examples:
            - Some transaction
        status:
          $ref: '#/components/schemas/Status5'
          examples:
            - POSTED
        type:
          $ref: '#/components/schemas/Type7'
          examples:
            - DEBIT
        posted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Posted At
          examples:
            - '2022-05-04T11:30:00Z'
        transacted_at:
          type: string
          format: date-time
          title: Transacted At
          examples:
            - '2022-05-04T11:30:00Z'
        memo:
          anyOf:
            - type: string
            - type: 'null'
          title: Memo
          examples:
            - ''
        merchant_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Merchant Name
          examples:
            - Starbucks
        merchant_category_code:
          anyOf:
            - type: number
            - type: 'null'
          title: Merchant Category Code
          examples:
            - 5967
        location:
          $ref: '#/components/schemas/Location'
      additionalProperties: true
      type: object
      required:
        - external_id
        - description
        - status
        - type
        - transacted_at
        - location
      title: Transaction1
    DailyTotal:
      properties:
        date:
          type: string
          title: Date
        net_total:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Net Total
        transaction_count:
          type: integer
          title: Transaction Count
      type: object
      required:
        - date
        - net_total
        - transaction_count
      title: DailyTotal
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    Type4:
      type: string
      enum:
        - CHECKING
        - SAVINGS
        - LOAN
        - CREDIT_CARD
        - INVESTMENT
        - LINE_OF_CREDIT
        - MORTGAGE
        - PROPERTY
        - CASH
        - INSURANCE
        - PREPAID
        - CHECKING_LINE_OF_CREDIT
        - ANY
      title: Type4
      description: The account's type
    Subtype1:
      type: string
      enum:
        - MONEY_MARKET
        - CERTIFICATE_OF_DEPOSIT
        - AUTO
        - STUDENT
        - SMALL_BUSINESS
        - PERSONAL
        - PERSONAL_WITH_COLLATERAL
        - HOME_EQUITY
        - BOAT
        - POWERSPORTS
        - RV
        - HELOC
        - PLAN_401_K
        - PLAN_403_B
        - PLAN_529
        - IRA
        - ROLLOVER_IRA
        - ROTH_IRA
        - TAXABLE
        - NON_TAXABLE
        - BROKERAGE
        - TRUST
        - UNIFORM_GIFTS_TO_MINORS_ACT
        - PLAN_457
        - PENSION
        - EMPLOYEE_STOCK_OWNERSHIP_PLAN
        - SIMPLIFIED_EMPLOYEE_PENSION
        - SIMPLE_IRA
        - PLAN_ROTH_401_K
        - FIXED_ANNUITY
        - VARIABLE_ANNUITY
        - HSA
        - TAX_FREE_SAVINGS_ACCOUNT
        - INDIVIDUAL
        - REGISTERED_RETIREMENT_INCOME_FUND
        - CASH_MANAGEMENT_ACCOUNT
        - EMPLOYEE_STOCK_PURCHASE_PLAN
        - REGISTERED_EDUCATION_SAVINGS_PLAN
        - PROFIT_SHARING_PLAN
        - UNIFORM_TRANSFER_TO_MINORS_ACT
        - PLAN_401_A
        - SARSEP_IRA
        - FIXED_ANNUITY_TRADITIONAL_IRA
        - VARIABLE_ANNUITY_TRADITIONAL_IRA
        - SEPP_IRA
        - INHERITED_TRADITIONAL_IRA
        - FIXED_ANNUITY_ROTH_IRA
        - VARIABLE_ANNUITY_ROTH_IRA
        - INHERITED_ROTH_IRA
        - COVERDELL
        - ADVISORY_ACCOUNT
        - BROKERAGE_MARGIN
        - CHARITABLE_GIFT_ACCOUNT
        - CHURCH_ACCOUNT
        - CONSERVATORSHIP
        - CUSTODIAL
        - DEFINED_BENEFIT_PLAN
        - DEFINED_CONTRIBUTION_PLAN
        - EDUCATIONAL
        - ESTATE
        - EXECUTOR
        - GROUP_RETIREMENT_SAVINGS_PLAN
        - GUARANTEED_INVESTMENT_CERTIFICATE
        - HRA
        - INDEXED_ANNUITY
        - INVESTMENT_CLUB
        - IRREVOCABLE_TRUST
        - JOINT_TENANTS_BY_ENTIRITY
        - JOINT_TENANTS_COMMUNITY_PROPERTY
        - JOINT_TENANTS_IN_COMMON
        - JOINT_TENANTS_WITH_RIGHTS_OF_SURVIVORSHIP
        - KEOUGH_PLAN
        - LIFE_INCOME_FUND
        - LIVING_TRUST
        - LOCKED_IN_RETIREMENT_ACCOUNT
        - LOCKED_IN_RETIREMENT_INVESTMENT_FUND
        - LOCKED_IN_RETIREMENT_SAVINGS_ACCOUNT
        - MONEY_PURCHASE_PLAN
        - PARTNERSHIP
        - PLAN_409_A
        - PLAN_ROTH_403_B
        - REGISTERED_DISABILITY_SAVINGS_PLAN
        - REGISTERED_LOCKED_IN_SAVINGS_PLAN
        - REGISTERED_PENSION_PLAN
        - REGISTERED_RETIREMENT_SAVINGS_PLAN
        - REVOCABLE_TRUST
        - ROTH_CONVERSION
        - SOLE_PROPRIETORSHIP
        - SPOUSAL_IRA
        - SPOUSAL_ROTH_IRA
        - TESTAMENTARY_TRUST
        - THRIFT_SAVINGS_PLAN
        - INHERITED_ANNUITY
        - CORPORATE_ACCOUNT
        - LIMITED_LIABILITY_ACCOUNT
        - VEHICLE_INSURANCE
        - DISABILITY
        - HEALTH
        - LONG_TERM_CARE
        - PROPERTY_AND_CASUALTY
        - UNIVERSAL_LIFE
        - TERM_LIFE
        - WHOLE_LIFE
        - ACCIDENTAL_DEATH_AND_DISMEMBERMENT
        - VARIABLE_UNIVERSAL_LIFE
        - ROTH
        - ROLLOVER
        - OTHER
        - ANNUITY
        - TRANSFERRABLE_ON_DEATH
      title: Subtype1
      description: The account’s subtype
    AccountBalances:
      properties:
        currency_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency Code
          examples:
            - USD
        balance:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Balance
          examples:
            - '100.00'
        available_balance:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Available Balance
          examples:
            - '50.99'
        credit_limit:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Credit Limit
          examples:
            - '200.00'
      additionalProperties: true
      type: object
      title: AccountBalances
    Status5:
      type: string
      enum:
        - POSTED
        - PENDING
      title: Status5
    Type7:
      type: string
      enum:
        - DEBIT
        - CREDIT
      title: Type7
    Location:
      properties:
        latitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Latitude
          examples:
            - '40.730610'
        longitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Longitude
          examples:
            - '-73.935242'
      additionalProperties: true
      type: object
      title: Location
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: PAT
      description: >-
        Bearer authentication with a personal access token (prefix `pat_`).
        Generate tokens in the Truv web app under Settings → API keys.

````