Skip to main content
GET
Get User Bank Transactions V2

Authorizations

Authorization
string
header
required

Bearer authentication with a personal access token (prefix pat_). Generate tokens in the Truv web app under Settings → API keys.

Query Parameters

transacted_at_from
string
required

Start date for the transaction window (inclusive, YYYY-MM-DD).

Example:

"2025-01-01"

transacted_at_to
string

End date for the transaction window (inclusive, YYYY-MM-DD). Defaults to today.

Example:

"2025-12-31"

categories
string | null

Comma-separated category slugs to include (e.g. 'income,transfer'). Omit to include all categories.

Maximum string length: 1000
Example:

"income,transfer"

transaction_type
enum<string> | null

Filter by transaction type. Omit to include both debits and credits.

Available options:
DEBIT,
CREDIT
Example:

"DEBIT"

account_ids
string | null

Comma-separated account IDs to include. Omit to include all accounts.

Example:

"acc_001,acc_002"

min_amount

Minimum transaction amount (absolute value). Inclusive.

Example:

"10.00"

max_amount

Maximum transaction amount (absolute value). Inclusive.

Example:

"500.00"

merchant
string | null

Case-insensitive substring match on merchant name or description.

Example:

"starbucks"

exclude_categories
string | null

Comma-separated category slugs to exclude (e.g. 'transfer,uncategorized').

Maximum string length: 1000
sort_by
enum<string>
default:date

Sort transactions by date, by absolute amount, or by review: the queue's own order, most damaging question first. review ignores sort_order and requires needs_review.

Available options:
date,
amount,
review
Example:

"date"

sort_order
enum<string>
default:desc

Sort direction: ascending or descending.

Available options:
asc,
desc
Example:

"desc"

page
integer | null

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.

Required range: x >= 1
Example:

1

page_size
integer | null

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.

Required range: 10 <= x <= 500
Example:

100

include_hidden
boolean
default:false

Include user-hidden transactions alongside visible ones. Hidden transactions can be unhidden; permanently deleted transactions are never returned regardless.

Example:

true

review_state
enum<string> | null

Keep only transactions in this review state, meaning whether the user has acted on them. Omit for every state. Note unreviewed covers everything the user has simply never touched, which is most of their history: for the needs-review chip use needs_review instead. UNREVIEWED is the read-side default for a transaction with no review row, and is never written, so an absent row and an explicit unreviewed row mean the same thing.

Available options:
unreviewed,
reviewed,
dismissed
Example:

"unreviewed"

needs_review
boolean
default:false

Keep only the transactions we would actually ask about: the current review queue, with anything the user has answered or already settled by editing the transaction or making a merchant rule removed. This is what the Needs review chip filters on, and count on the response is the number beside it.

Example:

true

Response

Paginated bank transactions (v2, ClickHouse-backed).

Response model of the v2 transaction endpoints.

The route class returns a JSONResponse, so this shapes the OpenAPI spec but never validates or serializes a payload.

count
integer
required

Total transactions matching the filters, across all pages.

accounts
Account · object[]
required

Accounts the returned transactions belong to.

transactions
TransactionSchema · object[]
required
daily_totals
DailyTotal · object[]

Net total per calendar day, reflecting the same filters.

merchant_logos
Merchant Logos · object

Logo URL per merchant name present in the response.

next
string | null

Relative URL of the next page, when paginated.

previous
string | null

Relative URL of the previous page, when paginated.