Sfoglia il riferimento

Transazioni

20 endpoint · Le descrizioni degli endpoint sono in inglese.

List transactions, newest date first (date DESC, id DESC), with cursor pagination and filters

GET/households/{householdId}/transactions

read:transactions

Parametri

Nome	Posizione	Obbligatorio	Descrizione
limit	query	Facoltativo	1..100, default 50
cursor	query	Facoltativo	Opaque cursor from the previous page (nextCursor)
maxAmountCents	query	Facoltativo	Cents
minAmountCents	query	Facoltativo	Cents
search	query	Facoltativo	-
dateTo	query	Facoltativo	YYYY-MM-DD
dateFrom	query	Facoltativo	YYYY-MM-DD
source	query	Facoltativo	-
statuses	query	Facoltativo	Comma-separated statuses (any-of); supersedes `status` when both are sent
status	query	Facoltativo	-
attention	query	Facoltativo	Rows waiting on the user: needs-review, plus actionable uncategorized outflows that are not reconciled (the account attention count’s predicate)
uncategorized	query	Facoltativo	Only rows in the budget’s uncategorized bucket: bare outflows on on-budget accounts (cleared or reconciled), never transfer legs or system rows
needsReview	query	Facoltativo	true = rows awaiting a category decision, false = the rest
hasFlag	query	Facoltativo	Only transactions that carry a flag
flagIds	query	Facoltativo	Comma-separated flag ULIDs (any-of), max 20
hasTag	query	Facoltativo	-
tagMode	query	Facoltativo	-
tagIds	query	Facoltativo	Comma-separated tag ULIDs, max 20
tagId	query	Facoltativo	-
payeeId	query	Facoltativo	-
categoryId	query	Facoltativo	-
accountId	query	Facoltativo	-

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions

Risposta200 · Success

Create a transaction (with optional splits and tags)

POST/households/{householdId}/transactions

write:transactions

Corpo della richiesta

json

{  "accountId": "01J8ME9AZ2K3W7X4V5T6R7Q8S9",  "date": "2026-06-22",  "amountCents": -4250,  "currency": "EUR",  "payeeName": "Local supermarket",  "categoryId": "01J8ME9B7QW3ZK5X2V8T4R6S1D",  "memo": "Weekly groceries"}

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions \     -d '{"accountId":"01J8ME9AZ2K3W7X4V5T6R7Q8S9","date":"2026-06-22","amountCents":-4250,"currency":"EUR","payeeName":"Local supermarket","categoryId":"01J8ME9B7QW3ZK5X2V8T4R6S1D","memo":"Weekly groceries"}'

Risposta201 · Success

Get one transaction with its splits

GET/households/{householdId}/transactions/{transactionId}

read:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/{transactionId}

Risposta200 · Success

Update a transaction (replaces splits and tagIds when provided)

PATCH/households/{householdId}/transactions/{transactionId}

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Corpo della richiesta

json

{  "categoryId": "01J8ME9B7QW3ZK5X2V8T4R6S1D",  "status": "cleared"}

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: $(uuidgen)" \     -X PATCH https://api.vokse.ai/households/current/transactions/{transactionId} \     -d '{"categoryId":"01J8ME9B7QW3ZK5X2V8T4R6S1D","status":"cleared"}'

Risposta200 · Success

Soft-delete a transaction

DELETE/households/{householdId}/transactions/{transactionId}

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X DELETE https://api.vokse.ai/households/current/transactions/{transactionId}

Risposta204 · No content

Accept the AI-suggested category and clear the suggestion fields. The accepted row becomes ground truth for future kNN predictions.

POST/households/{householdId}/transactions/{transactionId}/accept-suggestion

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/accept-suggestion

Risposta200 · Success

"Not a duplicate": clear the possible-duplicate flag an ambiguous auto-match left on a bank import.

POST/households/{householdId}/transactions/{transactionId}/dismiss-match

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/dismiss-match

Risposta200 · Success

Link this transaction and a counterpart as the two legs of one transfer. The budget engine then recognises card payments through the shared group (ADR 0099).

POST/households/{householdId}/transactions/{transactionId}/link-transfer

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/link-transfer

Risposta200 · Success

Merge a bank import with the hand-entered row it duplicates: the hand-entered row survives (payee, category, memo, tags, splits) and takes the bank date; the bank row is folded into it. Undoable (ADR 0105).

POST/households/{householdId}/transactions/{transactionId}/match

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/match

Risposta200 · Success

Rows this transaction could be merged with as the same purchase: a bank import lists hand-entered twins, a hand-entered row lists bank twins (same account, amount and currency, within 7 days; ADR 0105)

GET/households/{householdId}/transactions/{transactionId}/match-candidates

read:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/{transactionId}/match-candidates

Risposta200 · Success

Reject the AI-suggested category. The row stays uncategorized.

POST/households/{householdId}/transactions/{transactionId}/reject-suggestion

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/reject-suggestion

Risposta200 · Success

Remove a single tag from a transaction

DELETE/households/{householdId}/transactions/{transactionId}/tags/{tagId}

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio
tagId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X DELETE https://api.vokse.ai/households/current/transactions/{transactionId}/tags/{tagId}

Risposta204 · No content

Counterpart rows this transaction could be linked to as one transfer: exact opposite amount, same currency, another account, within 7 days (ADR 0099)

GET/households/{householdId}/transactions/{transactionId}/transfer-candidates

read:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/{transactionId}/transfer-candidates

Risposta200 · Success

Unlink a two-leg transfer: both legs keep payee and category but drop the shared group. Forbidden while a leg is reconciled.

POST/households/{householdId}/transactions/{transactionId}/unlink-transfer

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/unlink-transfer

Risposta200 · Success

Separate a merged pair again: the bank import comes back as its own row and the hand-entered row gets its previous date and status. Forbidden while reconciled.

POST/households/{householdId}/transactions/{transactionId}/unmatch

write:transactions

Parametri

Nome	Posizione	Obbligatorio
transactionId	path	Obbligatorio

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/unmatch

Risposta200 · Success

Bulk-create transactions (up to 500 in one shot)

POST/households/{householdId}/transactions/bulk

write:transactions

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/bulk

Risposta201 · Success

Bulk-update a subset of transactions with the same patch

PATCH/households/{householdId}/transactions/bulk-update

write:transactions

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X PATCH https://api.vokse.ai/households/current/transactions/bulk-update

Risposta200 · Success

Per-day money in, money out and count for a window of up to 92 days (the calendar): converted to the base currency, plus the face-value totals per currency

GET/households/{householdId}/transactions/daily-summary

read:transactions

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/daily-summary

Risposta200 · Success

How many hand-entered rows are still pending at least N days after their date on bank-fed accounts (the stale pending sweep, ADR 0105)

GET/households/{householdId}/transactions/stale-pending-count

read:transactions

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/stale-pending-count

Risposta200 · Success

Create a double-entry transfer between two accounts (both legs share a transfer group)

POST/households/{householdId}/transactions/transfer

write:transactions

Richiesta di esempio

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/transfer

Risposta201 · Success