List transactions for one account or several (keyset paginated)
const url = 'https://api.tovarifinancial.com/transactions?sort=asc&status=all&uncategorized=1&transferState=matched';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.tovarifinancial.com/transactions?sort=asc&status=all&uncategorized=1&transferState=matched' \ --header 'Authorization: Bearer <token>'Two modes, chosen by WHICH account parameter is sent — exactly one of accountId and accountIds (KAN-3657). Both run the same filters, search, sort and keyset paging.
One account (accountId) — the account register. The body carries the account summary and every row its runningBalanceCents (the tiered register balance: cleared rows build to the Cleared balance, uncleared and pending rows continue from it to the Working balance). There is no lookback limit. An unknown account, or one in another household, is 404.
Several accounts (accountIds) — every row carries accountId, accountName, accountMaskLast4 and accountType, and transferGroupId pairs the two legs of a transfer. There is NO summary and NO runningBalanceCents key. Rows of every status are limited to the last 3 years: the effective from is the later of the requested from and lookbackFrom (the caller’s local today minus 36 months), and a to before lookbackFrom is an empty 200. Only open accounts of the caller’s household can be selected; a foreign, unknown or closed id answers ONE identical 400 — identify it by fieldErrors.accountIds, never by message text — and the client should refetch its account list and retry. accountIds=all (KAN-3675) reads EVERY open account of the household, however many — the server resolves it, so it is never refused for an unavailable id, and a household with no open account gets an empty 200 page. includeClosed is not honoured here.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”One account id — the single-account register. MUTUALLY EXCLUSIVE with accountIds: exactly one of the two must be present, and neither or both is a 400 with fieldErrors.accountIds.
ONE comma-separated value of 1-50 account UUIDs — the several-accounts read (KAN-3657). Ids are trimmed and duplicates dropped (first-seen order kept); one id here is still the several-accounts mode. MUTUALLY EXCLUSIVE with accountId. An empty list, a non-uuid entry, more than 50 distinct ids, or the parameter REPEATED (?accountIds=a&accountIds=b) is a 400 with fieldErrors.accountIds. Or exactly the token all (KAN-3675): every open account of the caller’s household, resolved by the server and NOT capped at 50. The token is lower-case and stands alone — ALL or all mixed with ids is the same 400.
Calendar date, ‘YYYY-MM-DD’
Start date ‘YYYY-MM-DD’. A malformed value is 400. With accountIds the server raises it to the lookback floor (lookbackFrom on the response) when it is earlier or absent; it can never widen it.
Calendar date, ‘YYYY-MM-DD’
End date ‘YYYY-MM-DD’. A malformed value is 400.
Sort direction by transaction date. Anything other than asc sorts descending.
Filter by settlement status. uncleared is manually-entered rows not yet cleared. pending is the register’s Pending section: rows Plaid reports as pending. unsettled is both together (uncleared and pending). all, absent, or an unrecognised value applies no narrowing and is never a 400.
Search over the bank description, payee name and memo, and the notes on a split transaction’s lines (a split row appears once however many of its lines match). When the term contains a digit it ALSO matches the amount, sign-agnostically, after $, ,, whitespace, - and − (U+2212) are stripped — so −$1,234.56, -1234.56 and 1,234.56 all find a ±$1,234.56 row. An over-long term is clamped, never rejected.
1 or true returns uncategorized rows only. Any other value applies no narrowing and is never a 400.
Narrow to rows in one transfer state: matched, settled, or needs_review (derived, never stored). An unrecognised value applies no narrowing and is never a 400.
Narrow to rows entered by one household member (their user id). A value that is not a uuid applies no narrowing and is never a 400.
Page size (default 50, at most 100). A missing, non-numeric, zero or negative value falls back to the default and a larger one is clamped to the maximum — never a 400.
Opaque keyset cursor from the previous page’s nextCursor; a malformed value is 400.
Responses
Section titled “Responses”One account: rows + running balance summary. Several accounts: rows with their account line, the uncategorized count and the lookback floor. The two bodies are disjoint; the parameter sent decides which one arrives.
object
object
object
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
object
Calendar date, ‘YYYY-MM-DD’
Integer minor units (cents)
Integer minor units (cents)
object
object
Calendar date, ‘YYYY-MM-DD’
Integer minor units (cents)
The account’s last digits (2-4), or null when none is recorded.
Uncategorized rows across the selected accounts within the effective date range (after the lookback floor) and the request’s status, createdBy and search filters — independent of the page, the cursor, transferState and the uncategorized toggle itself.
Always the server’s lookback floor — the caller’s local today (X-Client-Timezone) minus 36 months — whatever from was requested. No row of any status dated before it is returned.
Example
{ "data": { "transactions": [ { "status": "uncleared", "categorySource": "user", "transferDirection": "out", "transferState": "matched" } ] }}Validation failed — see errorCode / fieldErrors. Every account-scope refusal is VALIDATION_ERROR with a fieldErrors.accountIds entry, the stable discriminator: neither or both of accountId/accountIds; a malformed, empty, over-long or repeated accountIds; and, in several-accounts mode, any id that is not an open account of the caller’s household — one identical body for a foreign, unknown or closed id. A malformed from, to or cursor is the same 400 keyed by that field.
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Missing, invalid, or expired bearer token
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Authenticated, but the tenant gate refuses the request until the caller resolves a precondition. errorCode is one of EMAIL_NOT_VERIFIED, POLICY_ACCEPTANCE_REQUIRED, or SUBSCRIPTION_REQUIRED, evaluated in exactly that order (contract term CCR-1: email verification first, then policy acceptance, then subscription — so a subscriber who has merely not re-accepted the current policies always sees POLICY_ACCEPTANCE_REQUIRED). A POLICY_ACCEPTANCE_REQUIRED body additionally carries details.outstanding (the policy versions still to accept) and details.firstAcceptance. The SUBSCRIPTION_REQUIRED arm is INERT unless the server-side BILLING_ENABLED flag is exactly the string true; while it is off, only the first two codes are reachable. Not retryable as sent — resolve the named condition, then resend.
object
Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.
object
Active policy versions the user has not yet accepted.
object
True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.
Example
{ "errorCode": "EMAIL_NOT_VERIFIED"}Single-account mode only: the accountId account was not found or is not owned by the caller org
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Internal error (no internal detail leaked)
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Service temporarily unavailable — errorCode is SERVICE_UNAVAILABLE. A TRANSIENT, RETRYABLE condition rather than a defect in the request: a query that exceeded its time budget, a lost or refused database connection, a saturated connection pool, or an outage at an upstream provider the request depends on (the authentication provider, or the bank data provider on a bank-connection operation). The identical request may succeed on retry — back off briefly and, on a write, resend the same X-Idempotency-Key where the operation accepts one.
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}