cursor on lists, page_token on the transaction reads).
Amounts are decimal strings with a separate ISO 4217 currency, dates are ISO 8601, and countries are ISO alpha-3.
Reads never bill.
Accounts
GET /v3/bank/connections/{id}/accounts/ lists the accounts of a connection, and GET /v3/bank/accounts/{account_id}/ returns one.
Use
account_ref to recognise a bank account when a person connects it again, and id for everything inside one connection.
Balances
GET /v3/bank/accounts/{account_id}/balances/ returns typed balances with their reference dates.
type is booked, available or expected, and iso_type carries the bank’s ISO 20022 code where the bank gives one.
Transactions
GET /v3/bank/accounts/{account_id}/transactions/ reads a date range.
It takes date_from and date_to (calendar dates as the bank reports them, inclusive), status (booked or pending, both by default), limit (up to 500) and page_token.
It sorts by effective_date descending, then id.
idis Didit’s, stored at first sight. The same movement keeps its id across reads, syncs and renewals.identity_qualitysays how strong that guarantee is.bank_referenceandroute_idare stable.derivedmeans the movement was matched by its content, so a bank correction can appear as oneremovedand oneadded.statusisbookedorpending. A pending transaction has its own id. When the bank books it, the booked transaction arrives asadded, the pending one asremovedwithreason: pending_booked, andpending_idis set only where the bank links them.amountis signed: negative is money out.directionrepeats the sign.bank_referenceis the bank’s immutable entry reference,nullwhere the bank does not provide one. Didit never invents it.categoryis Didit’s own categorisation, when one applies.- A correction by the bank to a booked transaction is
modified. A reversal is a new transaction, withreverses_idwhen the bank links it.
Fields a bank does not send are null
Every field a bank does not send isnull.
The institution lists the fields it is known to send in transaction_fields, together with pending_transactions, pending_linkage, balance_types and history_days_max, so nobody discovers gaps in production.
Use the sparse_fields test customer in the sandbox to test your code against a bank that sends little.
Paging a date range
Keep reading withpage_token while has_more is true.
The token pins the read’s snapshot for one hour: additions after the first page are not in it, each row is served in its current state, and a row removed during paging drops out of later pages and shows up in the change feed.
An expired token answers 410 page_expired: restart the read from its original query.
The change feed
GET /v3/bank/connections/{id}/transactions/sync/ returns what changed across all accounts of a connection since a cursor.
- An empty cursor returns every current transaction as
addedwithreset: true. Replace your copy with it instead of adding to it. - Keep paging with
page_tokenwhilehas_moreis true. Storenext_cursoronly after a response withhas_more: false, and if paging fails midway restart from the cursor you stored. - A cursor is opaque and bound to the connection and the environment. The change log is replayable for 90 days. An older cursor answers
410 cursor_expiredwithbootstrap: true: start again from an empty cursor and replace your copy. removed[].reasonispending_booked,pending_expired,bank_removedoraccess_removed.
Headers
Both transaction reads return theX-RateLimit-* headers (600 reads and 300 writes per minute per application, 429 with Retry-After beyond that) and X-Bank-Last-Synced-At.
API limits and the bank’s own limits on fetching are separate things: see Refresh bank data on demand.