Banking
Choose a workflow for accounts, imported records, reconciliation, and rules
Last Updated: 2026-08-26
Version: 2.1
Banking has three separate jobs: connect a bank account, import its activity, and reconcile that activity to accounting transactions. Keep those jobs separate in the UI and use the guide for the task being built.
Choose A Workflow
| Task | Use this guide |
|---|---|
| Explain transaction or rule suggestions | Reconcile Bank Records |
| Create suggestion or automatic bank rules | Bank Rules |
| Connect Plaid and map feeds to GL accounts | Bank Accounts and Connections |
| Import user-provided bank files | Import Data from CSV |
| Create or edit the matched accounting entry | Transactions |
| Diagnose provider connection failures | Connection Health |
Core Model
| Resource | Meaning |
|---|---|
| Account | The GL account used by transactions, journals, statements, and balances |
| AccountConnection | An optional Plaid or provider identity linked to one bank Account |
| BankRecord | Imported bank activity from a feed or CSV |
| Transaction | The balanced accounting entry reconciled to a BankRecord |
| BankRule | A saved condition and allocation that proposes or creates a Transaction |
The Account is the posting target. An AccountConnection is only an external identity and is never a second GL bank account.
Bank Records And Matching
Read Reconcile Bank Records for the complete workflow. In short:
- Request unmatched BankRecords with transaction sets and rule suggestions.
- Explain candidates from the returned
matchDetails, listing, reservation, and proposed transaction fields. - Ask the manager to choose when the response marks candidates as ambiguous.
- Dry-run the selected reconciliation or saved-rule run.
- Apply it, then re-read the BankRecord and Transaction.
The API returns two different suggestion types:
| Suggestion | What it points to |
|---|---|
matchingTransactionSets[] | One exact proposal containing one to five Transactions |
matchingRules[] | A saved BankRule and the Transaction it would create |
Do not treat response order as a confidence score. The reconciliation guide documents ranking, ambiguity, and the fields a manager should compare.
Bank Rules
Bank rules are already part of the matching workflow. A rule can:
- match deposits or expenses by direction, bank-account scope, description, and amount conditions;
- create fixed, percentage, merchant-fee, or remainder allocations;
- remain a manager-confirmed suggestion with
mode=suggest; or - authorize automatic creation and reconciliation with
mode=autoCreateAndMatch.
Read Bank Rules for preview, priority, tie handling, allocation rules, and examples.
Plaid Connect Sessions
Plaid setup uses one server-owned session across start, completion, and final configuration. Read Bank Accounts and Connections for create, update, replacement, account mapping, Hostaway branding, and recovery behavior.
Safe UI Loop
- Read the current resource, capabilities, locks, and issues.
- Render API-provided suggestions and configuration choices.
- Preview or dry-run where the endpoint supports it.
- Apply the confirmed choice using stable resource IDs.
- Re-read state after any mutation or provider action.
Do not recreate provider eligibility, matching explanations, allocation math, or lock decisions in the client.