Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dualentry.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Banking Connections: Paths, Sync, and Security

DualEntry links your organization to live bank data through financial connections: authenticated links to certified third-party aggregators that pull account metadata and transactions into DualEntry. Authentication happens in the aggregator’s hosted flow - bank credentials are entered there, not in DualEntry. DualEntry stores connection state, linked accounts, and imported financial transactions that you use for reconciliation and bank matching.

​
Where to add a banking connection

You manage every banking connection from a single page in the app. Sign in to DualEntry and navigate to Company → Bank Connections, then click Add Bank Connection to start a new connection. The Bank Connections page lists every connection on the organization, the financial accounts exposed by each one, and the current health of each connection (see Connection status). The same page is where you trigger an on-demand refresh, repair a connection that has dropped into a reconnect state, view the last successful sync timestamp, and remove a connection you no longer need. There is no separate settings area, hidden admin flow, or per-account dashboard - every connection operation routes through this page in both the UI and the API. Adding or repairing connections requires the bank connections permission on the authenticated organization. Users without the permission can still view existing connections and their status when their role allows it, but cannot create, repair, or delete a connection. If you need to add a connection and the Add Bank Connection button is hidden or disabled, ask an admin to grant the permission rather than attempting a workaround through the API.

​
What a banking connection does

A connection represents one consent relationship between your organization and a financial institution - for example, one login at a bank that may expose multiple accounts. DualEntry keeps a financial connection record per organization, tracks status and sync timestamps, and attaches financial accounts (the aggregator’s view of each bank account) to your internal ledger bank accounts where you map them. One connection can fan out into many accounts. A treasury login that exposes a checking account, a sweep account, and three sub-accounts becomes one financial connection with five financial accounts attached. Each financial account is mapped independently to its own GL cash or liability account, so a single bank login still reconciles cleanly to discrete ledger accounts. After data arrives, downstream workflows (reconciliation, rules, and bank match) operate on financial transactions tied to those financial accounts - not on raw aggregator payloads. This abstraction is what lets the same reconciliation, rule, and matching logic apply uniformly whether the data came from an aggregator-backed connection, a manual upload, or a non-standard connection.

​
Connection paths

DualEntry supports three paths for getting bank data into the ledger. Every account in scope must be assigned a path before connections begin. Coverage of the standard path is determined by the certified aggregators and is subject to change at their discretion.
PathWhen it appliesWhat you do
Standard connectionThe account is supported by a certified aggregator and validated by DualEntry against your specific institution and account type (business checking, sweep, sub-account, for-benefit-of (FBO) account, and so on).Click Add Bank Connection and complete the aggregator’s hosted flow. DualEntry then syncs balances and transactions automatically.
Manual uploadThe account is not supported by a certified aggregator, or you elect not to use one.Provide transaction data in a DualEntry-approved file format (CSV or BAI) on a defined cadence - at minimum, monthly by the 5th business day of the following month. You are responsible for completeness, accuracy, and timeliness.
Non-standard connectionThe account is not supported by a certified aggregator and you require automated ingestion.DualEntry, at its sole discretion and subject to feasibility review, contracts with a third-party provider or builds a custom connector. Non-standard connections are subject to additional fees quoted per account in your Order Form.
If a certified aggregator deprecates, throttles, or changes a connection - events DualEntry does not control - DualEntry works in good faith to migrate the affected account to manual upload or a non-standard connection. Migration to a non-standard connection may incur additional fees.

​
Data that syncs and how it maps to your books

Bank data flows in three directions: in from the aggregator, into DualEntry’s internal financial accounts and transactions, and back out to the workflows that act on it. Each direction has different scope and limits, summarized below. Inbound from the bank (read-only aggregation). DualEntry receives the account list, masked identifiers, balances where the aggregator exposes them, and transaction history according to the aggregator’s retention and product settings. Standard connections sync at the cadence supported by the aggregator, typically daily. Inside DualEntry. Each synced external account becomes a financial account linked to your organization. You associate that financial account with a ledger bank account in DualEntry so imported activity lines up with the correct general ledger cash account. Transactions land as financial transactions on that financial account; they are inputs to reconciliation and automation, not automatic journal postings on their own. Historical backfill. The depth of history at initial sync is determined by the aggregator and is typically capped at 90 days. Deeper history must be brought in through a data migration rather than the live feed. Not in scope. Banking connections are read-only. DualEntry does not originate ACH, wire payments, or account changes through these connections.

​
Connection lifecycle and operations

A banking connection moves through a defined lifecycle from initial creation through ongoing sync, periodic refresh, repair when credentials expire, and eventual deletion. DualEntry exposes a discrete operation for each stage so you can drive it from the UI, the API, or background tasks. Create (connect). DualEntry creates a pending connection and returns the aggregator’s hosted flow. The user enters credentials, approves any required scopes, and confirms which accounts to expose. Complete. After the user finishes the hosted flow, DualEntry completes the connection - exchanging tokens with the aggregator where needed, attaching the resolved financial institution, moving the connection out of pending, and enqueueing an initial sync. Sync. A sync refreshes connection metadata, financial accounts, and transaction data from the aggregator into DualEntry. Scheduled and task-driven syncs run in the background; you can also trigger a refresh-and-sync from the UI or API. Refresh. On-demand refresh asks the aggregator for fresher data. DualEntry enforces a per-connection refresh cooldown of one hour between manual refresh or refresh-and-sync calls to limit cost and aggregator throttling. Repair / reconnect. When credentials expire or the bank requires re-authentication, the connection moves to a reconnect state. Repair returns a new hosted-flow session in update mode so the user can reauthorize without creating a duplicate logical bank link. Delete. Deleting a connection removes aggregator-side access where possible, clears stored credentials, marks the connection inactive, and unlinks ledger accounts that pointed at financial accounts on that connection so your chart of accounts does not reference stale feed accounts.

​
Connection status

Connection status reflects whether DualEntry can currently pull data from the bank and whether anyone needs to take action. Use it as the single signal for connection health on dashboards, alerts, and audit reviews. Statuses are normalized strings on the connection record. The most common values are:
  • pending - connection created but the user has not finished the hosted flow.
  • in_progress - DualEntry is exchanging tokens or running the initial sync.
  • active - the connection is healthy and producing data.
  • partially_active - some accounts are syncing, others are not.
  • reconnect_required - the user must reauthenticate, typically due to credential expiry or bank-side MFA.
  • reconnect_available - new accounts are exposed by the aggregator; the user can opt to add them.
  • degraded - the aggregator reports intermittent issues and data may lag.
  • expired / deleted - the connection is no longer producing data.
The UI and API surface a reconnectable flag when the connection is in a state that expects user action or when new accounts are available from the aggregator. Timestamps. last_sync_at updates whenever DualEntry runs a sync attempt, successful or not. successfully_aggregated_at reflects the aggregator’s last successful aggregation time when the aggregator supplies it, so it can lag a manual sync click if the bank has not produced new data yet.

​
Customer responsibilities

Once a connection is live, ongoing health depends on actions only the account holder can take. DualEntry monitors connection state and surfaces what needs attention, but cannot satisfy these requirements on your behalf.
  • Credentials. Maintain valid bank credentials at the institution. Password rotations and lockouts at the bank break the connection until you reauthenticate from the Bank Connections page.
  • MFA prompts. Complete multi-factor authentication challenges when the institution presents them during connection or reauthentication. Persistent failure to complete MFA is not a DualEntry support obligation.
  • Reauthentication. Reauthenticate connections in reconnect_required within the cadence your accounting close requires. Stale connections continue to display historical transactions but do not pull new activity.
  • Manual upload cadence. For accounts on manual upload, provide transaction files no less frequently than monthly, by the 5th business day of the following month, in CSV or BAI format. You are responsible for completeness, accuracy, and timeliness of the data you provide.

​
Security and compliance posture

DualEntry enforces several boundaries between your data, the aggregator, and other tenants on the platform. The points below summarize the protections built into the connection layer.
  • No shared secrets in the browser. Bank passwords are collected only in the aggregator’s hosted UI, never in DualEntry’s interface or API.
  • Scoped access. Connection APIs require explicit bank connections permissions on the authenticated organization.
  • Credential storage. Aggregator access tokens, where DualEntry holds them, are stored in an encrypted JSON field at rest.
  • Transport encryption. All traffic between DualEntry and aggregators runs over TLS, and the aggregator’s hosted flow redirects back to DualEntry over HTTPS only.
  • Tenant isolation. All connection queries are constrained to the authenticated organization; cross-tenant access is rejected at the API.
  • Webhooks and background work. Aggregator webhooks and background tasks update connection health, pull transactions, and repair stale cursors. Operational logs use structured events suitable for internal monitoring.
Together, these controls keep banking credentials out of DualEntry’s perimeter, scope every read to a single organization, and produce an event trail your auditors can sample. For platform-level compliance posture, including SOC 2 scope and access logging, refer to your security review materials rather than relying on this page alone.

​
API access

The Financial Connections V2 API exposes the entire connection lifecycle programmatically. Routes live under /api/financial_connections/v2/connections/ and include connect, complete, repair, refresh, trigger-sync, list, get, status, and delete - each mirroring an operation described above. Authentication uses standard DualEntry organization-scoped credentials, and cross-tenant access is rejected at the API layer. The per-connection refresh cooldown of one hour applies whether a refresh is initiated from the UI or the API, so a UI refresh and an API refresh share the same window. Status values returned by the API match the values surfaced in the UI, so an integration that consumes the API can reuse the same health signals end users see. Use the API when you need to drive the connect flow from your own application, surface connection health in an internal monitoring stack, or sync banking state into a downstream system. For full request and response schemas, see the OpenAPI reference shipped with the developer documentation.
Last modified on May 28, 2026