# BankSync Documentation # BankSync BankSync syncs bank transactions, balances, holdings, trades, and loans from 11,000+ banks to Google Sheets, Notion, Airtable, and Excel, or to AI agents via the BankSync MCP server (https://mcp.banksync.io). Every docs page is available as Markdown — append `.md` to any /docs URL, or send `Accept: text/markdown`. --- # Managing Your Plan & Billing > View your plan and usage, upgrade or downgrade, update your payment method, and manage workspace members and roles in BankSync Settings. > Source: https://banksync.io/docs/account-billing/managing-your-plan Everything about your subscription and team lives in **Settings**. This guide shows you where each control is, so you can check your plan and usage, switch plans, keep your card up to date, and manage who has access to your workspace. > **Before you start:** 'Billing and Members are workspace-level settings. You need the Owner or Admin role to change them. Without it, both sections open in view-only mode (you\\'ll see a "View only" banner). Open Settings from the left navigation, then use the Workspace group in the sidebar.' [![A tour of the Billing panel: the current plan with usage meters for every quota, and the plan picker comparing all tiers with the annual-billing toggle.](https://cdn.banksync.io/videos/billing-panel-tour.poster.a882cd2793dcc201.png)](https://cdn.banksync.io/videos/billing-panel-tour.f26d65cbb057a403.mp4) [Watch: A tour of the Billing panel: the current plan with usage meters for every quota, and the plan picker comparing all tiers with the annual-billing toggle.](https://cdn.banksync.io/videos/billing-panel-tour.f26d65cbb057a403.mp4) ## View your plan and usage The **Billing** section opens on its **Overview** tab and shows your current plan at a glance. **Check your plan** 1. **Open Settings → Billing** — In the settings sidebar, under the Workspace group, click Billing. 2. **Read the Your plan card** — The hero card shows your plan name, its status (active, trialing, or past\_due), the sync cadence badge, and a billing line such as "$6/mo · billed yearly · renews May 12, 2027". 3. **Review Usage this month** — The Usage this month panel shows meters for your current month against your plan limits. Click Detailed report to open your invoices and billing history. ![BankSync Settings Billing Overview showing the 'Your plan' hero card with the Standard plan name, an active status chip, a Daily syncs cadence badge, the billing line '$6/mo, billed yearly, renews May 12, 2027', and a Manage billing button, above a 'Usage this month' panel with meter bars for Banks (5/5), Documents (92/100), and API requests (18.4k/25k).](https://cdn.banksync.io/screenshots/billing/plan-usage.c1f6fd95941198c7.png "The Billing Overview 'Your plan' card and 'Usage this month' meters.") The Billing section uses tabs across the top: **Overview**, **Payment**, **Invoices**, and (on Professional and Business) **Add-ons**. A **Cancel plan** tab appears when your subscription is active or trialing. ## Upgrade or downgrade your plan Plan changes are made from the **Switch plan** area on the Billing Overview tab. **Switch plans** 1. **Find the Browse plans grid** — On the Billing Overview tab, scroll to Switch plan / Browse plans. Use the monthly/yearly toggle to compare prices (yearly saves about 20%). 2. **Click the plan you want** — Your current plan's card is disabled. Picking any other tier starts the change. Changes are prorated and take effect immediately. 3. **Confirm an upgrade** — Upgrades go straight to a confirmation step that shows what changes and the proration. Confirm to switch. If there is no card on file, you'll be routed to add one first. 4. **Resolve anything blocking a downgrade** — If a lower plan can't fit your current usage (too many banks, feeds, members, or portals), a checklist appears listing what to clear. Use Resolve manually to jump to the relevant page, fix it, then return and continue. 5. **Confirm the change** — Once the checklist passes (or if nothing needed fixing), confirm the consequences screen to commit. A "Plan switched" message confirms the new plan. > **Add-ons:** On the Professional and Business plans, the Add-ons tab lets you buy extra capacity beyond your plan's base limits: Extra Bank Connections, Extra Team Seats, Extra Extractor Blocks, and (on Business) Extra Client Portals. Use the plus and minus buttons, then Save Changes. Add-on charges are prorated. ### Cancel or resume To cancel, use the quiet **Cancel subscription** link at the bottom of the Overview tab, or the **Cancel plan** tab. Cancelling stops future charges at the end of the current billing period; your access continues until then. If a cancellation is already scheduled, a banner offers a **Resume** option to keep the plan without interruption. ## Update your payment method Saved cards live on the **Payment** tab. **Add or replace a card** 1. **Open Settings → Billing → Payment** — The Payment tab lists your Saved Payment Methods, each showing the card brand, last 4 digits, expiry, and a Default badge on the active card. 2. **Add a new card** — Click Add New Payment Method and enter your card details in the secure form. After it's added, the list refreshes automatically. 3. **Remove an old card** — Click the trash icon next to a card and confirm in the Delete Payment Method dialog. > **Past-due or declined card:** If a charge fails, your plan shows past\_due. Add a working card on the Payment tab and remove the failed one so it becomes the default. The next billing retry uses the default card. If the status doesn't clear after you've added a valid card, contact support from Settings → Support and we'll re-run the charge. ## Manage members and roles Team access is controlled in **Settings → Members**. **Invite and manage teammates** 1. **Open Settings → Members** — The Members section lists everyone in the workspace and any pending invitations. 2. **Invite a teammate** — Click Invite Member, enter their Email Address, choose a Role (Admin, Editor, or Viewer), then click Send Invite. They appear under pending invitations until they accept. 3. **Change a role** — Use the role dropdown next to a member to switch between Admin, Editor, and Viewer. 4. **Remove a member or invitation** — Click the trash icon next to a member to remove them. For a pending invite, use the refresh icon to resend or the trash icon to cancel it. 5. **Transfer ownership** — As the Owner, click the crown icon next to a member to make them the new Owner. The four roles are: **Owner** (full control, including billing and ownership transfer), **Admin** (manage members and billing), **Editor** (create and edit feeds and data), and **Viewer** (read-only). If you reach your plan's seat limit, an upgrade nudge appears with a **Manage Add-ons** link to buy extra seats. Members who aren't the Owner can use **Leave Workspace** to remove themselves. ## Confirm it worked - The **Your plan** card on the Billing Overview shows the expected plan name and an active (or trialing) status. - After a plan change, you see a "Plan switched" confirmation and the new plan's limits in the Usage this month meters. - On the **Payment** tab, your new card carries the **Default** badge. - In **Members**, an invited teammate appears under pending invitations, and role changes are reflected by the badge next to each name. ## Troubleshooting > **Common issues:** Controls greyed out or a "View only" banner: you need the Owner or Admin role. Add-ons tab missing: it only shows on Professional and Business while the subscription is active or trialing. Can't invite more members: you've hit your seat limit, so use Manage Add-ons to add seats or upgrade. A downgrade won't go through: clear the items in the checklist (over-cap banks, feeds, members, or portals) first. ## Next steps [Manage your feeds](/docs/bank-feeds/managing-feeds) ## Related guides - [Changing or canceling your plan](/docs/account-billing/changing-your-plan): the full upgrade, downgrade-checklist, and cancellation flows, plus what each plan includes. - [Workspaces and team members](/docs/workspaces/members-and-roles): inviting, re-roling, and removing the members you manage from Settings. - [Deleting your account](/docs/account-billing/deleting-your-account): closing your account entirely, including the 14-day grace period. --- # Changing or canceling your plan > Upgrade, downgrade, or cancel your BankSync plan, including the downgrade checklist and how plan caps change. > Source: https://banksync.io/docs/account-billing/changing-your-plan Your plan can change as your needs do. This guide walks through upgrading to a higher tier, downgrading to a lower one (and clearing anything that blocks it), and canceling without losing access before your period ends. Everything happens on the Billing **Overview** tab in Settings. [![Upgrading a plan: the Billing panel with current usage meters, the plan picker with the annual pricing toggle, choosing Professional, the upgrade confirmation with proration details, checkout, and the success screen with limits unlocked instantly.](https://cdn.banksync.io/videos/billing-upgrade.poster.a882cd2793dcc201.png)](https://cdn.banksync.io/videos/billing-upgrade.801a70e495f9df7d.mp4) [Watch: Upgrading a plan: the Billing panel with current usage meters, the plan picker with the annual pricing toggle, choosing Professional, the upgrade confirmation with proration details, checkout, and the success screen with limits unlocked instantly.](https://cdn.banksync.io/videos/billing-upgrade.801a70e495f9df7d.mp4) [![Downgrading or canceling a plan from Billing: the lower plan card opens a downgrade confirmation, and the cancellation flow explains downgrade alternatives plus access through the end of the billing period.](https://cdn.banksync.io/videos/downgrade-and-cancel.poster.612ce53c10ab9392.png)](https://cdn.banksync.io/videos/downgrade-and-cancel.17fcb61a7f6860b4.mp4) [Watch: Downgrading or canceling a plan from Billing: the lower plan card opens a downgrade confirmation, and the cancellation flow explains downgrade alternatives plus access through the end of the billing period.](https://cdn.banksync.io/videos/downgrade-and-cancel.17fcb61a7f6860b4.mp4) > **Before you start:** 'Billing is a workspace-level setting, so you need the Owner or Admin role to change plans. Without it, Billing opens in view-only mode (you\\'ll see a "View only" banner). Open Settings from the left navigation, then click Billing under the Workspace group in the sidebar. To pay for an upgrade you\\'ll also need a card on file (added during checkout).' ![The BankSync Billing Overview showing the current plan card with status and cadence, and a Usage this month panel with meters for banks, documents, and API requests against the plan limits.](https://cdn.banksync.io/screenshots/billing/plan-usage.c1f6fd95941198c7.png "The Billing Overview, where you change your plan and watch usage against your plan caps.") ## What changes between plans When you move up or down a tier, your workspace limits change immediately. These are the caps that the upgrade and downgrade flows check against. | Plan | Bank connections | Feeds | Members (seats) | Sync cadence | Roles | | ------------ | ---------------- | --------- | --------------- | --------------------- | ---------------------------- | | Free | 0 | 1 | 1 | Weekly | Owner only | | Starter | 1 | 2 | 1 | Weekly | Owner only | | Standard | 5 | 5 | 1 | Daily, Weekly | Owner, Viewer | | Professional | 15 | Unlimited | 5 | Hourly, Daily, Weekly | Owner, Admin, Editor, Viewer | | Business | 30 | Unlimited | 10 | Hourly, Daily, Weekly | Owner, Admin, Editor, Viewer | A few more limits also change with the tier: | Plan | Integrations | Documents / month | Client portals | API rate | MCP rate | | ------------ | ------------ | ----------------- | -------------- | ------------- | ------------- | | Free | 1 | 10 | 0 | No API access | No MCP access | | Starter | 3 | 30 | 0 | No API access | No MCP access | | Standard | 3 | 100 | 0 | 30 req/min | 15 req/min | | Professional | Unlimited | 1,000 | 5 | 150 req/min | 30 req/min | | Business | Unlimited | 2,000 | 20 | 750 req/min | 300 req/min | The monthly document quota covers the Document Extractor and resets on the 1st of each month. > **Need more without changing tiers:** 'On Professional and Business, the Add-ons tab lets you buy extra capacity (Extra Bank Connections, Extra Team Seats, Extra Extractor Blocks, and on Business, Extra Client Portals) on top of these base caps. Add-on charges are prorated.' ## Upgrade to a higher plan Upgrading is the quick path: pick the tier, confirm, and the new limits apply right away. **Move up a tier** 1. **Open Settings → Billing** — In the settings sidebar, under the Workspace group, click Billing. The page opens on the Overview tab. 2. **Find the plan grid** — Scroll to the Browse plans / Switch plan grid. Use the monthly/yearly toggle to compare prices (yearly is the cheaper per-month rate). Your current plan's card shows a disabled "Current plan" button. 3. **Click the higher plan** — Pick Standard, Professional, or Business. An upgrade goes straight to a confirmation dialog that lists what changes (higher caps, new roles, faster sync) and the prorated charge. 4. **Add a card if prompted** — If you have no payment method on file, you're routed to a secure card form first. Enter your card details to continue; BankSync stores the card with Stripe, not in BankSync itself. 5. **Confirm the change** — Click the confirm button on the consequences screen. The subscription is created and the plan activates immediately. A "Plan switched" message confirms the new tier. > **Switching while past-due:** 'If a charge has failed, your plan shows past\_due. Switching plans in that state resets the subscription and drops any add-ons (extra banks, seats), and the confirmation dialog warns you before you commit. Clear the past-due status first by adding a working card on the Payment tab. See /docs/account-billing/managing-your-plan for updating your payment method.' ## Downgrade to a lower plan Downgrades run a validation checklist before anything changes, because a smaller plan may not fit your current usage. Some issues are fixed for you; over-cap issues you must clear yourself. **Move down a tier** 1. **Click the lower plan in the grid** — On the Billing Overview tab, pick a tier below your current one. BankSync calls its precheck and, if there is anything to resolve, opens the validation checklist instead of going straight to confirmation. 2. **Review the checklist** — Each item is grouped by severity. Auto-fixable items can be resolved in place; over-cap items must be cleared by you; informational and acknowledge-only items just need your consent. 3. **Apply the auto-fixes** — For an incompatible role (for example, Admins or Editors when the target plan does not allow them), click the offered fix to demote those members to Viewer. For a sync schedule that the lower plan can't run (such as Hourly on a plan that tops out at Daily), the fix relaxes those feeds to an allowed cadence. Applying the fix unblocks Continue. 4. **Resolve over-cap items yourself** — If you have more banks, feeds, members, or client portals than the lower plan allows, those rows are a hard block with no auto-fix. Click Resolve manually to jump to the relevant page, remove items down to the cap, then return to the checklist. 5. **Continue and confirm** — Once every must-resolve item is cleared, Continue enables. Confirm the consequences screen to commit the downgrade. A clean downgrade (nothing over cap, no incompatible roles or schedules) skips the checklist entirely and goes straight to confirmation. The checklist sorts work into three kinds: | Item kind | Example | How it's resolved | | ----------------------- | ----------------------------------------------------------------- | --------------------------------------------------- | | Auto-fixable (role) | Admins or Editors on a plan that allows only Owner and Viewer | One-click demote to Viewer | | Auto-fixable (schedule) | A feed set to Hourly moving to a plan without Hourly | One-click change to an allowed cadence | | Over-cap (hard block) | More banks, feeds, members, or portals than the lower plan allows | You remove items down to the cap (Resolve manually) | | Acknowledge-only | API access or MCP that the lower plan turns off | Confirm you understand the feature stops working | > **Free and past-due block new bank connections:** Dropping to Free (0 bank connections) or letting a charge go past\_due will block connecting new banks. Existing usage over the new cap must be brought down before the downgrade will commit, so you won't be left silently over the limit, but plan to disconnect or remove the excess yourself. ## Cancel your subscription Canceling stops future charges but keeps your access until the end of the period you've already paid for. **Cancel or resume** 1. **Open the cancel control** — On the Billing Overview tab, use the quiet Cancel subscription link at the bottom, or the Cancel plan tab (it appears while your subscription is active or trialing). 2. **Confirm the cancellation** — Your plan is scheduled to lapse to Free at the end of the current billing period. You keep full access, with your current limits, until that date. 3. **Resume before it takes effect** — While a cancellation is pending, a banner offers a Resume option. Click it to clear the scheduled cancellation and keep your plan with no interruption. Switching to a different plan also clears a pending cancellation, and the confirmation dialog tells you when that happens. ## Confirm it worked - After an upgrade or downgrade, the **Your plan** card on the Billing Overview shows the expected plan name with an active (or trialing) status, and the Usage this month meters reflect the new limits. - You see a "Plan switched" confirmation when a change commits. - After canceling, the plan shows a scheduled-cancellation banner with the date access ends and a Resume option. - After resuming, that banner disappears and the plan reads as active again. ## Troubleshooting > **Common issues:** Controls greyed out or a "View only" banner: you need the Owner or Admin role. Downgrade won't continue: the checklist still has an unresolved must-resolve item. Apply the offered auto-fix, or for over-cap rows (banks, feeds, members, portals) use Resolve manually to remove items down to the new cap, then come back. Can't connect new banks: you're on Free or past\_due. Add a working card on the Payment tab to clear past\_due, or upgrade to a tier with bank connections. Upgrade asks for a card: there's no payment method on file yet. Enter one in the secure form to continue. ## Next steps - **Manage your plan and billing** — View usage, update your payment method, and find invoices. - **Workspaces and members** — Adjust roles and seats before a downgrade so the role check passes. [Manage your plan & billing](/docs/account-billing/managing-your-plan) ## Related guides - [Managing your plan and billing](/docs/account-billing/managing-your-plan): usage meters, payment methods, invoices, and add-ons. - [Workspaces and team members](/docs/workspaces/members-and-roles): fix seats and roles that block a downgrade. - [Removing a bank](/docs/connecting-banks/removing-a-bank): bring bank connections under a lower plan's cap. - [MCP server guide](/docs/mcp/overview): what you gain (or lose) in agent access when MCP availability changes with your tier. --- # Deleting your account > Request account deletion, the 14-day grace period, how to cancel, and exactly what is permanently removed. > Source: https://banksync.io/docs/account-billing/deleting-your-account Deleting your BankSync account is permanent and removes everything you own, so it is deliberately a multi-step process with a grace period and email confirmation. This is different from deleting a single workspace: account deletion takes down every workspace you own plus your login itself. If you only want to remove one workspace, see the workspace guide linked at the end. [![Requesting account deletion from Settings: the Delete Account page lists owned workspaces, memberships, the 14-day grace period, and the confirm-by-typing form for the account email and DELETE MY ACCOUNT phrase.](https://cdn.banksync.io/videos/delete-account.poster.66f15fa7daffc755.png)](https://cdn.banksync.io/videos/delete-account.92746242dc298b2d.mp4) [Watch: Requesting account deletion from Settings: the Delete Account page lists owned workspaces, memberships, the 14-day grace period, and the confirm-by-typing form for the account email and DELETE MY ACCOUNT phrase.](https://cdn.banksync.io/videos/delete-account.92746242dc298b2d.mp4) > **This is permanent after the grace period:** Once the 14-day grace period ends, deletion runs and cannot be undone. Every workspace you own is deleted (its banks and provider credentials, feeds, integrations, API keys, and client portals), any active subscription is cancelled, your memberships in other people's workspaces are removed, and your profile and login are erased. Data you already synced to external services (Google Sheets, Notion, a database, and so on) is not affected. > **Before you start:** 'Cancel any active subscription first. If a workspace you own has an active or trialing subscription, the Delete My Account button stays disabled and BankSync shows a "Cancel your subscription first" notice. Cancel it from Settings, Billing before you continue so you are not charged during the grace period. You should also decide what happens to workspaces you own: deleting your account deletes them outright, so transfer ownership to a teammate first if anyone else needs to keep them.' ## Request account deletion The control lives in your User Profile, under the **Account** tab (shown in red). **Open the Account tab and request deletion** 1. **Open your User Profile** — Click your profile in the top navigation to open the User Profile dialog. 2. **Switch to the Account tab** — Click the red Account tab. You'll see "Delete Account" and a list of exactly what will be removed: the workspaces you own (by name), your membership in any other workspaces, and your user account, profile, and login credentials. 3. **Cancel subscriptions if prompted** — If a "Cancel your subscription first" notice appears, the Delete My Account button is disabled. Go to Settings, Billing, cancel the subscription, then return to this tab. 4. **Click Delete My Account** — A confirmation panel opens asking you to type your email address and the exact phrase to confirm. 5. **Type your email and the confirm phrase** — Type your account email, then type the phrase exactly as shown. The Request Deletion button stays disabled until both match. 6. **Click Request Deletion** — A "Deletion Requested" toast appears telling you to check your email, and the tab switches to the pending state. > **The exact confirm phrase:** 'In the second field you must type DELETE MY ACCOUNT in capitals, exactly. If it does not match you\\'ll see "Please type "DELETE MY ACCOUNT" exactly", and if the email field does not match your account email you\\'ll see "Email address does not match".' ## Confirm via the email link Requesting deletion does not schedule anything on its own. You must click the link in the confirmation email. **Confirm the request** 1. **Open the confirmation email** — BankSync sends a confirmation email to your account address. The Account tab also reminds you it was sent. 2. **Click the confirmation link before it expires** — The confirmation link is valid for 72 hours. Clicking it schedules the deletion. 3. **Note your scheduled date** — After confirming, the tab shows "Account Scheduled for Deletion" with the exact date your account and workspaces will be permanently removed, 14 days out. ## What happens during the 14-day grace period After you confirm, there is a 14-day window before anything is deleted. Your workspaces stay fully functional the whole time, so feeds keep syncing and the app works normally. | Stage | What it means | Status shown | | ---------- | ------------------------------------------------------------------------- | ------------------------------ | | Requested | You submitted the request, confirmation email sent, nothing scheduled yet | Deletion Requested (pending) | | Confirmed | You clicked the email link, deletion is scheduled for a date 14 days out | Account Scheduled for Deletion | | Reminder | BankSync emails you a reminder a few days before the scheduled date | Account Scheduled for Deletion | | Processing | The scheduled date passed, your data is being removed | Account deletion in progress | | Done | Everything below is permanently deleted | Account no longer exists | What gets deleted when the grace period ends: - **Every workspace you own** — Each owned workspace cascades like a workspace deletion: connected banks and their provider credentials, feeds, integrations, API keys, and client portals are all removed. - **Active subscriptions** — Any active subscription on a workspace you own is cancelled as part of deletion. - **Your memberships** — You are removed from every other workspace where you were a member. Those workspaces themselves are not deleted. - **Profile and login** — Your user account, profile, and login credentials are erased. You will be signed out. ## Cancel before the scheduled date You can stop the deletion at any time before the scheduled date, and it takes effect immediately. **Cancel a pending or scheduled deletion** 1. **Open the Account tab, or use the cancel link in the email** — In the Account tab, a pending request shows a Cancel Request button and a scheduled request shows a Cancel Deletion button. The reminder and confirmation emails also include a cancel link. 2. **Click Cancel** — A "Deletion Cancelled" toast confirms it. 3. **Check the tab returns to normal** — The Account tab returns to the default "Delete Account" state, meaning there is no longer an active request. > **One active request at a time:** 'You can only have one active deletion request at a time. Requesting a second while one is active is rejected with an "already exists" error. Cancelling clears the current request, and you are then free to start a new one whenever you like.' ## Confirm it worked - After requesting, the Account tab shows **Deletion Requested** and tells you to check your email. - After clicking the email link, the tab shows **Account Scheduled for Deletion** with a specific date and a **Cancel Deletion** button. - After cancelling, the tab returns to the default **Delete Account** state with no scheduled date. - When deletion finally runs, the app shows **Account deletion in progress** and signs you out; afterward your login no longer works. ## Troubleshooting > **Common issues:** 'Delete My Account is greyed out: a workspace you own still has an active or trialing subscription. Cancel it from Settings, Billing, then come back. Request Deletion stays disabled: your email or the confirm phrase does not match exactly (the phrase is case-sensitive). The confirmation email link does nothing: it expired after 72 hours, so start a new request. "Already exists" error: you already have an active request, so cancel it first if you want to start over. Nothing happened after the scheduled date: processing can take a few minutes; the tab shows "Account deletion in progress" while it completes.' [Delete a single workspace instead](/docs/workspaces/deleting-a-workspace) ## Related guides - [Deleting a workspace](/docs/workspaces/deleting-a-workspace): remove one workspace instead of your whole account (note: that flow has no grace period). - [Workspaces and team members](/docs/workspaces/members-and-roles): transfer ownership with the crown icon first if your team should keep a workspace you own. - [Managing your plan and billing](/docs/account-billing/managing-your-plan): cancel an active subscription, which is required before you can request deletion. --- # REST API Guide > Orientation for the BankSync REST API: base URL, authentication, resources, errors, and rate limits by plan. > Source: https://banksync.io/docs/api/rest-api The BankSync REST API gives you programmatic access to everything in your workspace: banks, accounts, transactions, balances, investments, loans, feeds, sync jobs, and enrichments. Use it to build custom integrations, automate reporting, or wire BankSync into your own application. This page is the orientation map. Each topic links to a focused guide, and every endpoint is documented in the generated API reference. - **RESTful design** — Standard HTTP methods, JSON requests and responses - **Scoped API keys** — Per-key permission scopes, enforced server-side - **Full workspace access** — Read data, manage feeds, and trigger syncs ## Base URL All requests use the same base URL: ```text https://api.banksync.io/v1 ``` ## Quick start **Make your first request** 1. **Create an API key** — In the BankSync app, open Settings > Developers and create a key. Copy the bsk\_ secret when it is shown; it appears only once. See the API keys guide for scopes and expiration. 2. **Authenticate with the X-API-Key header** — Send the key on every request. Keys are bound to one workspace, so no workspace ID header is needed. 3. **List your feeds** — Call GET /feeds to confirm the key works and see your configured feeds. ```bash curl -X GET "https://api.banksync.io/v1/feeds" \ -H "X-API-Key: bsk_your_api_key_here" ``` A `200 OK` with a JSON body means you are authenticated and correctly scoped. ## Authentication Every request requires your API key in the `X-API-Key` header. Keys carry `resource:action` scopes (for example `feeds:read`, `jobs:write`) that you choose at creation, so each integration gets exactly the access it needs. > **Keep your API key secure:** 'Never expose your key in client-side code, public repositories, or logs. Store it in an environment variable or a secrets manager. If a key is compromised, revoke it immediately in Settings > Developers and create a new one.' - [Authentication](/docs/api/authentication): header format, scopes, and request examples in curl, JavaScript, and Python. - [API keys](/docs/api/api-keys): creating, scoping, rotating, and revoking keys. ## Resources Everything hangs off your workspace. Banks contain accounts; accounts expose transactions, balances, trades, holdings, and loans; feeds move that data to your connected apps and produce jobs each time they run. - **Financial data** — Transactions, balances, trades, holdings, and loans, fetched live from your connected banks - **Banks & accounts** — List connected institutions and the accounts under each connection - **Feeds & jobs** — Read and manage feed configurations, trigger syncs (POST /feeds/:fid/sync), and track job status - **Enrichments** — Create and manage the Rule, Alert, and Memory enrichments that run during syncs See [Resources & data types](/docs/api/resources) for the full hierarchy, key fields per resource, pagination, and sync modes, or browse every endpoint in the API reference. ## Rate limits API throughput is set by your workspace plan. Free and Starter do not include REST API access. | Plan | API access | Rate limit | | ------------ | ---------- | ---------------- | | Free | No | n/a | | Starter | No | n/a | | Standard | Yes | 30 requests/min | | Professional | Yes | 150 requests/min | | Business | Yes | 750 requests/min | When you exceed your limit the API returns `429 Too Many Requests`; back off and retry with exponential delay. If you consistently need more headroom, upgrade your plan or contact support. ## Error handling The API uses conventional HTTP status codes and returns structured JSON errors with a `success: false` flag and a human-readable `error` message. | Code | Meaning | | ---- | --------------------------------------------- | | 400 | Bad request: missing fields or invalid format | | 401 | Missing, invalid, or revoked API key | | 403 | Key lacks the required scope | | 404 | Resource not found | | 422 | Feed configuration failed validation | | 429 | Rate limit exceeded | | 503 | Bank consent required (reconnect in the app) | The [Error handling guide](/docs/api/errors) covers the response format, validation errors, and a troubleshooting walkthrough for each code. ## AI agents instead of code? If you want an AI assistant (Claude, Cursor, ChatGPT, and others) to work with your BankSync data rather than writing HTTP calls yourself, use the hosted MCP server at `https://mcp.banksync.io`. It authenticates with the same API keys. See the [MCP server guide](/docs/mcp/overview). > **SDKs coming soon:** We're working on official SDKs for Python, Node.js, and other languages. Until then, the API is plain HTTPS + JSON and works with any HTTP client. [Browse the API reference](/docs/api/reference) ## Related guides - [Authentication](/docs/api/authentication): how to authenticate every request with `X-API-Key`. - [API keys](/docs/api/api-keys): create least-privilege keys and rotate them safely. - [Resources & data types](/docs/api/resources): the data model behind every endpoint. - [MCP server guide](/docs/mcp/overview): the same data exposed to AI agents over MCP. --- # Authentication > Learn how to authenticate with the BankSync API using API keys or bearer tokens. Understand scopes and permissions. > Source: https://banksync.io/docs/api/authentication The BankSync API and MCP server support two authentication methods. Choose the one that fits your use case. [![Creating the API key that authenticates your requests: opening Settings, the Developer section, creating a key named Production MCP Server with feeds and banks scopes, and copying the one-time bsk\_ key used as the Bearer token.](https://cdn.banksync.io/videos/api-keys-and-mcp.poster.a4bc2ee6ace134e3.png)](https://cdn.banksync.io/videos/api-keys-and-mcp.76edc41d298a567a.mp4) [Watch: Creating the API key that authenticates your requests: opening Settings, the Developer section, creating a key named Production MCP Server with feeds and banks scopes, and copying the one-time bsk\_ key used as the Bearer token.](https://cdn.banksync.io/videos/api-keys-and-mcp.76edc41d298a567a.mp4) ## API Key Authentication The recommended method for server-side integrations, scripts, and MCP clients. Pass your API key in the `X-API-Key` header with every request. ```text X-API-Key: bsk_your_key_here ``` ### Creating an API Key To create an API key, open the [BankSync app](https://app.banksync.io), click your workspace menu, and select `Developers`. From there you can name your key, choose which permission scopes it should have, and create it. ![The Developer settings panel before any API keys exist, showing an empty API Keys list with a Create Key button.](https://cdn.banksync.io/screenshots/api/keys-empty.5ea3b230ae5b39fe.png "The Developers panel before any keys are created.") ![The Create API Key dialog with a key name filled in and read and write permission scopes selected per resource.](https://cdn.banksync.io/screenshots/api/create-key-filled.30cd75c657c6d210.png "Name the key and select only the permission scopes you need.") ![The newly created API key revealed once, with a copy button and a warning that the key will not be shown again.](https://cdn.banksync.io/screenshots/api/key-revealed.7623162059957ddf.png "Copy your API key now: it is shown only once.") ### Key Format All BankSync API keys begin with the `bsk_` prefix followed by 44 random characters. For example: ```text bsk_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2 ``` ### Code Example ```bash curl -X GET "https://api.banksync.io/v1/banks" \ -H "X-API-Key: bsk_your_api_key_here" \ -H "Content-Type: application/json" ``` ```javascript const response = await fetch('https://api.banksync.io/v1/banks', { headers: { 'X-API-Key': process.env.BANKSYNC_API_KEY, 'Content-Type': 'application/json', }, }) ``` ```python import os import requests response = requests.get( "https://api.banksync.io/v1/banks", headers={ "X-API-Key": os.environ["BANKSYNC_API_KEY"], "Content-Type": "application/json", } ) ``` > **Security Best Practices** > > - Store API keys in environment variables, never in source code > - Never commit API keys to version control > - Rotate keys regularly and revoke any that may be compromised > - Use the minimum scopes required for your use case ## Bearer Token Authentication For web app integrations where the user is already signed in to BankSync, you can use a session token as a bearer token. This method is primarily used by the BankSync web application itself. ```text Authorization: Bearer X-Workspace-ID: ``` When using bearer token authentication, you must also include the `X-Workspace-ID` header to specify which workspace you are operating on. > **When to Use** > > Bearer token auth is best for browser-based apps where the user is already signed in to BankSync. For server-side scripts, CLI tools, and MCP clients, use API key authentication instead. ## Scopes & Permissions API keys are scoped to specific permissions. When creating a key, select only the scopes you need. | Resource | Read Scope | Write Scope | Read Access | Write Access | | ---------------- | ------------------ | ------------------- | ------------------------------------------------ | -------------------------------- | | Banks & Accounts | `banks:read` | `banks:write` | List/get banks, accounts | Connect/delete banks | | Feeds | `feeds:read` | `feeds:write` | List/get feeds | Create/update/delete feeds | | Jobs & Syncs | `jobs:read` | `jobs:write` | List/get jobs | Trigger syncs, cancel jobs | | Enrichments | `enrichments:read` | `enrichments:write` | List/get enrichments, preview rules | Create/update/delete enrichments | | Workspaces | `workspaces:read` | `workspaces:write` | List workspaces, integrations, members, API keys | Delete integrations | > **Note:** Write operations require both read AND write scopes. For example, creating a feed requires both `feeds:read` and `feeds:write`. > **Note:** API key management (creating and revoking keys) requires an authenticated session. API keys cannot self-manage: you must use the BankSync web app to create or revoke keys. --- # API keys > Create scoped BankSync API keys, copy the secret once, authenticate requests, and revoke keys. > Source: https://banksync.io/docs/api/api-keys An API key is a secret credential that gives programmatic access to your workspace through the BankSync REST API and the MCP server. Each key carries a fixed set of permission scopes you choose at creation, so a script or AI agent gets exactly the access it needs and nothing more. [![Creating an API key in the BankSync app: opening Settings, the Developer section, the API Keys panel, naming the key Production MCP Server, selecting the feeds and banks scopes, revealing and copying the bsk\_ key once, and the note that one key works for both the REST API and MCP clients.](https://cdn.banksync.io/videos/api-keys-and-mcp.poster.a4bc2ee6ace134e3.png)](https://cdn.banksync.io/videos/api-keys-and-mcp.76edc41d298a567a.mp4) [Watch: Creating an API key in the BankSync app: opening Settings, the Developer section, the API Keys panel, naming the key Production MCP Server, selecting the feeds and banks scopes, revealing and copying the bsk\_ key once, and the note that one key works for both the REST API and MCP clients.](https://cdn.banksync.io/videos/api-keys-and-mcp.76edc41d298a567a.mp4) > **Before you start:** You need the Admin or Owner role in the workspace to create or revoke keys. API keys are > managed only from the BankSync web app: a key cannot create or revoke other keys. API access also > depends on your plan, so if you see an "isn't included on your plan" banner on the API Keys panel, > upgrade before creating a key. ## What an API key looks like Every key starts with the `bsk_` prefix followed by a long random string. The full secret is shown to you exactly once, at the moment of creation. After that, BankSync only ever displays the first 8 characters (the **key prefix**, for example `bsk_a3f5`) so you can identify the key in lists without exposing the secret. ```text bsk_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2 ``` ## Create an API key **Create a key** 1. **Open Developer settings** — Click your workspace menu, then select Developers. The API Keys panel opens and lists any existing keys, or shows "No API keys yet" if you have none. 2. **Start a new key** — Click Create Key. The create view opens with fields for the key name, expiration, and permissions. 3. **Name the key** — Type a descriptive name in Key Name, for example "Production MCP Server". The name is only a label to help you recognize the key later. 4. **Choose an expiration** — Under Expiration, pick one of 30 days, 60 days, 90 days, 1 year, or Never. Short-lived keys reduce the blast radius if a secret leaks. 5. **Select scopes** — Under Permissions, toggle the read and write actions you need per resource. Use Select all only if the key genuinely needs full access. You must select at least one permission to continue. 6. **Create it** — Click Create API Key. The reveal view appears with the full secret. 7. **Copy the secret immediately** — Click the copy icon (or select the text) and store the key somewhere safe. The screen warns that this is the only time it will be shown and it cannot be retrieved later. Click Done to return to the list. ![BankSync API Keys panel listing two keys: Production MCP Server with feeds and jobs read plus write scopes, and Reporting (read-only) with only read scopes, each showing the masked key prefix, an Active badge, created and expiry dates, and a revoke action, with a Create Key button below](https://cdn.banksync.io/screenshots/api/api-keys.c4c64ac282611b4f.png "The API Keys panel: each key shows its name, masked prefix, scopes (read in blue, write in amber), status, and dates.") > **The full key is shown only once:** 'BankSync stores only a SHA-256 hash of your key, never the plaintext. If you close the reveal view ("Done") without copying the secret, you cannot recover it: revoke the key and create a new one.' ## The scopes model Scopes follow a `resource:action` pattern (Stripe-style). There are two actions, `read` and `write`, across the resources below. Grant the least privilege a key needs: a reporting script usually needs only read scopes, while an automation that triggers syncs or creates feeds needs the matching write scopes. | Resource | Read scope | Write scope | Read access | Write access | | ------------ | ------------------- | -------------------- | ------------------------------------- | --------------------------------------------- | | Workspaces | `workspaces:read` | `workspaces:write` | Workspace metadata and membership | Modify workspace settings and members | | Banks | `banks:read` | `banks:write` | List and get banks and accounts | Connect and delete banks | | Feeds | `feeds:read` | `feeds:write` | List and get feeds | Create, update, delete feeds | | Jobs | `jobs:read` | `jobs:write` | List and get jobs | Trigger syncs, cancel jobs | | Enrichments | `enrichments:read` | `enrichments:write` | List and get enrichment rules | Create, update, delete rules | | Dashboards | `dashboards:read` | `dashboards:write` | View dashboards, widgets, and queries | Create, update, delete dashboards and widgets | | Portals | `portals:read` | `portals:write` | View client portals | Create, update, delete client portals | | Integrations | `integrations:read` | `integrations:write` | View destination integrations | Connect and remove integrations | > **Scopes and least privilege:** 'A write scope authorizes write actions for its resource. Some write paths read the resource first, so the safe choice is to grant both the read and write scope for any resource a key needs to modify. The dashboards, portals, and integrations scopes cover the corresponding surfaces of the app and MCP server.' ## Use the key Pass the key in the `X-API-Key` header on every request. The base URL for the REST API is `https://api.banksync.io/v1`. Because a key is bound to a single workspace, you do not need to send a workspace header. ```bash curl -X GET "https://api.banksync.io/v1/banks" \ -H "X-API-Key: bsk_your_api_key_here" \ -H "Content-Type: application/json" ``` Store the key in an environment variable rather than pasting it inline so it never lands in your shell history or source control. ```bash export BANKSYNC_API_KEY="bsk_your_api_key_here" curl -X GET "https://api.banksync.io/v1/banks" \ -H "X-API-Key: $BANKSYNC_API_KEY" ``` The same key authenticates the MCP server, so an AI client configured with it can call BankSync tools within the scopes you granted. See the [MCP server guide](/docs/mcp/overview) for client setup. ## List your keys On the **API Keys** panel, each existing key shows its name, the key prefix (for example `bsk_a3f5...`), an **Active** badge, the granted scopes (read in blue, write in amber, grouped by resource), the creation date, and the expiry. The full secret is never shown again, by design. ```bash curl -X GET "https://api.banksync.io/v1/workspaces/WORKSPACE_ID/api-keys" \ -H "Authorization: Bearer YOUR_SESSION_TOKEN" \ -H "X-Workspace-ID: WORKSPACE_ID" ``` > **Why this call uses a session token:** 'Creating and revoking keys are session-only: they need a signed-in Bearer token plus the X-Workspace-ID header, not an X-API-Key, because a key cannot mint or revoke other keys. Listing keys also accepts a key that has \`workspaces:read\`. In practice you do all key management from the web app.' ## Revoke a key **Revoke a key** 1. **Find the key** — On the API Keys panel, locate the key by its name and prefix. 2. **Start revocation** — Click the trash icon on the key's row (titled "Revoke key"). An inline Cancel / Revoke confirmation appears. 3. **Confirm** — Click Revoke. The key is invalidated immediately and removed from the active list. Revocation takes effect at once: any request using a revoked key gets a `401 Invalid or expired API key` response. There is no grace period and no way to reactivate, so rotate by creating a new key first, switching your integration over, then revoking the old one. ## Security best practices - **Store secrets safely** — Keep keys in environment variables or a secrets manager. Never commit them to version control or hard-code them. - **Least privilege** — Grant only the scopes a key needs. A read-only reporting job should not hold any write scope. - **Rotate regularly** — Set an expiration and rotate keys on a schedule. Create the replacement, cut over, then revoke the old key. - **Revoke leaked keys** — If a key is exposed in logs, a screenshot, or a repo, revoke it immediately and issue a new one. ## Confirm it worked Make a read request scoped to a permission you granted. A `200 OK` with a JSON body confirms the key is valid and correctly scoped. ```bash curl -i -X GET "https://api.banksync.io/v1/banks" \ -H "X-API-Key: $BANKSYNC_API_KEY" ``` | Response | Meaning | | ------------------ | ----------------------------------------------------------------------------------------------------------- | | `200 OK` | The key is valid and has the scope for this resource. | | `401 Unauthorized` | The key is missing, mistyped, expired, or revoked. | | `403 Forbidden` | The key is valid but lacks the required scope for this operation, or your plan does not include API access. | After revoking, repeat the same request: a `401` confirms the key is dead. ## Troubleshooting > **Every request returns 403 right after creating a key:** 'This usually means your plan does not include API or MCP access (you would have seen a lock banner on the API Keys panel), or the key is missing a scope the operation needs (remember write needs read too). Check the granted scopes in the list, and confirm your plan on the billing page.' - **`401` on a brand new key:** make sure you copied the full secret from the reveal view, with no truncation or trailing whitespace, and that you are sending it in `X-API-Key`, not `Authorization`. - **Lost the secret:** it cannot be recovered. Revoke the key and create a new one. - **Need to create or revoke keys via API:** you cannot. Key creation and revocation require a signed-in session in the web app (listing keys is available with a `workspaces:read` key). ## Next steps - [Authentication](/docs/api/authentication): full reference for API key and bearer token auth, headers, and scopes. - [REST API guide](/docs/api/rest-api): endpoints, request and response shapes, and pagination. - [MCP server guide](/docs/mcp/overview): connect an AI client to BankSync using your API key. --- # Resources & Data Types > Understand the BankSync data model: banks, accounts, transactions, balances, investments, loans, enrichments, feeds, jobs, and more. > Source: https://banksync.io/docs/api/resources An overview of every resource in the BankSync data model. Understanding this hierarchy helps you navigate the REST API and MCP tools effectively. ## Resource Hierarchy All resources are organized under a workspace. The tree below shows how resources relate to each other. ```text Workspace ├── Banks │ └── Accounts │ ├── Transactions │ ├── Balances │ ├── Trades │ ├── Holdings │ └── Loans ├── Enrichments │ ├── Rules │ ├── Alerts │ └── Memory ├── Feeds │ └── Jobs ├── Integrations └── API Keys ``` ## Banks A **bank** represents a connection to a financial institution via an open finance provider (Plaid, SaltEdge, or SnapTrade). Each bank connection gives you access to the institution's accounts and data. ### Key Fields | Field | Description | | ----------------- | ------------------------------ | | `id` | Unique bank ID | | `institutionName` | e.g. "Chase" | | `source` | plaid \| saltedge \| snaptrade | | `status` | connected \| error | | `createdAt` | ISO 8601 | ## Accounts Each bank connection contains one or more **accounts**: checking, savings, credit card, investment, loan, etc. Account data is fetched live from the financial institution. ### Key Fields | Field | Description | | ---------- | ----------------------- | | `id` | Account ID | | `name` | Account name | | `type` | checking, savings, etc. | | `subtype` | More specific type | | `currency` | ISO 4217 code | ## Transactions **Transactions** are individual account entries: purchases, deposits, transfers, fees, etc. The API supports date-range filtering and cursor-based pagination for large result sets. ### Key Fields | Field | Description | | ------------- | -------------- | | `id` | Transaction ID | | `amount` | Signed amount | | `description` | Payee/merchant | | `date` | YYYY-MM-DD | | `category` | Categorization | | `pending` | true/false | > **Pagination:** Use `from` and `to` query params for date filtering. For large results, use the `cursor` returned in the response to fetch the next page. ## Balances **Balances** represent the current state of an account. They are fetched live from the financial institution each time you request them. ### Key Fields | Field | Description | | ----------- | ---------------------------- | | `current` | Ledger balance | | `available` | Available to spend | | `limit` | Credit limit (if applicable) | | `currency` | ISO 4217 | | `asOf` | Timestamp of balance | ## Investments Investment data is split into two resources: **Trades** (buy/sell transactions) and **Holdings** (current positions). Investment data may require additional bank consent. ### Trades | Field | Description | | ---------- | ------------------- | | `ticker` | Symbol (AAPL) | | `type` | buy, sell, dividend | | `quantity` | Number of units | | `price` | Price per unit | | `amount` | Total value | | `date` | Trade date | ### Holdings | Field | Description | | -------------- | ------------------ | | `securityName` | e.g. "Apple Inc" | | `ticker` | Symbol | | `quantity` | Shares held | | `currentPrice` | Market price | | `currentValue` | Total market value | | `costBasis` | Original cost | > **Consent:** Some banks require explicit user consent for investment data. If you receive a 503 error, the user must re-authorize the bank connection in the BankSync app. ## Loans **Loan** data covers mortgages, auto loans, student loans, and other liabilities. Includes principal balance, interest rate, payment schedule, and maturity date. ### Key Fields | Field | Description | | ------------------------ | -------------------- | | `loanType` | mortgage, auto, etc. | | `principalBalance` | Outstanding | | `interestRatePercentage` | APR | | `nextPaymentAmount` | Next payment | | `nextPaymentDueDate` | Due date | ## Enrichments **Enrichments** are processing steps that run during every sync. They transform and annotate your financial data as it flows through the pipeline. There are three types: **Rules** (if/then auto-categorization), **Alerts** (notifications via email, Slack, SMS, or webhook), and **Memory** (remembers user edits in the destination and replays them). ### Key Fields | Field | Description | | -------------- | --------------------------------- | | `id` | Enrichment ID | | `name` | Display name | | `type` | rule \| alert \| memory | | `enabled` | Active toggle | | `dataType` | transactions, balances, etc. | | `feedIds` | Scoped feeds | | `allFeeds` | Apply to all feeds | | `order` | Pipeline position | | `ruleConfig` | Rules: conditions + actions | | `alertConfig` | Alerts: conditions + destinations | | `memoryConfig` | Memory: pattern + target fields | > **Singleton:** Only one Memory enrichment exists per workspace; it is keyed deterministically, so creating a Memory enrichment again via the API replaces the existing one rather than failing with a conflict. Rules and Alerts can have multiple instances. ## Feeds A **feed** is a data pipeline configuration that syncs financial data from a source (bank accounts) to a destination (Notion, Google Sheets, Airtable, etc.). Feeds define what data to sync, how to map fields, and when to run. ### Key Fields | Field | Description | | ------------------- | ---------------------------- | | `id` | Feed ID | | `name` | Human-readable name | | `source` | Source type | | `dataType` | transactions, balances, etc. | | `sourceConfig` | Source settings | | `destinationConfig` | Destination settings | | `fieldMappings` | Field mapping rules | | `schedule` | Cron schedule | ## Jobs A **job** represents a single execution of a feed sync. Jobs progress through these states: ```text in_progress → completed | failed | cancelled ``` ### Key Fields | Field | Description | | ----------------------- | -------------------- | | `id` | Job ID | | `status` | Current state | | `createdAt` | When created | | `startedAt` | When execution began | | `completedAt` | When finished | | `transactionsProcessed` | Row count | ### Sync Modes When triggering a sync via `POST /feeds/:fid/sync`, the sync mode depends on the feed's data type and the parameters you provide: - **Incremental (cursor-based)**: Default for transaction feeds. Syncs only new data since the last sync. No request body needed. - **Date range**: Pass `startDate` and `endDate` (YYYY-MM-DD) in the request body. Required for trade feeds, optional for transaction feeds. - **Snapshot**: Balance, holdings, and loan feeds always sync the latest snapshot. No request body needed. > **Concurrency:** Only one job can be active per feed at a time. Triggering a sync while one is already running returns a `409` error. ## Integrations **Integrations** are connected destination apps: Notion, Google Sheets, Airtable, Excel, and others. Feeds use integrations as their sync destination. You can list and disconnect integrations via the API. ## API Keys **API keys** grant programmatic access to the BankSync API and MCP server. Each key has a set of permission scopes that control what it can access. See the [Authentication guide](/docs/api/authentication) for details on creating and managing API keys. > **Note:** API key management (creating and revoking keys) requires an authenticated session. Keys cannot self-manage: use the BankSync web app. --- # Error Handling > HTTP status codes, error response format, and troubleshooting guide for the BankSync API. > Source: https://banksync.io/docs/api/errors The BankSync API uses conventional HTTP status codes and returns structured JSON error responses to help you diagnose and fix issues quickly. ## Error Response Format All error responses include a `success` field set to `false` and a human-readable `error` message. ```json title="Standard Error Response" { "success": false, "error": "Human-readable error message" } ``` Validation errors (422) may include additional `errors` and `warnings` arrays with detailed information: ```json title="Validation Error Response (422)" { "success": false, "error": "Feed configuration is invalid", "errors": ["sourceConfig.accounts is required for sync feeds"], "warnings": ["No fieldMappings provided - defaults will be used"] } ``` ## HTTP Status Codes The API uses standard HTTP status codes to indicate the success or failure of a request. | Code | Meaning | When It Happens | | ---- | ----------------- | -------------------------------------------------- | | 200 | OK | Request succeeded | | 201 | Created | Resource created (POST) | | 400 | Bad Request | Missing required fields, invalid format | | 401 | Unauthorized | Missing or invalid API key / Bearer token | | 403 | Forbidden | Insufficient scopes or role too low | | 404 | Not Found | Resource doesn't exist or was deleted | | 409 | Conflict | Job already in terminal state (cancel) | | 422 | Validation Error | Feed config failed semantic validation | | 429 | Too Many Requests | Rate limit exceeded | | 500 | Internal Error | Server error: contact support | | 503 | Consent Required | Bank requires re-authorization for investment data | ## Troubleshooting Common issues and how to fix them. ### 401: "Invalid or missing API key" - Ensure you are passing the key in the `X-API-Key` header, not as a query parameter. - Check that the key starts with `bsk_` and has not been revoked. - Make sure there are no extra whitespace or newline characters in the key. ### 403: "Insufficient permissions" - Your API key may not have the required scopes. Check the scopes table in the [Authentication](/docs/api/authentication) guide. - Write operations require both the read and write scopes for that resource. - The workspace role associated with the key creator may be too low (e.g., viewer trying to write). ### 404: "Resource not found" - Double-check the resource IDs (bankId, accountId, etc.) in your URL path. - The resource may have been deleted. List the parent resource to verify it exists. - Ensure you are using the correct workspace: API keys are scoped to the workspace where they were created. ### 422: "Feed configuration is invalid" - Review the `errors` array in the response for specific field-level issues. - Use the validate feed endpoint to pre-flight check your configuration before creating or updating. - Check the `warnings` array for non-blocking issues that may affect your sync. ### 429: "Too many requests" - Back off and retry with exponential delay. - Reduce the frequency of your requests or batch operations where possible. - Contact support if you need higher rate limits for your use case. ### 503: "Consent required" - The bank connection requires re-authorization, typically for investment account data. - Direct the user to the BankSync app to reconnect the bank and grant the required permissions. --- # Register an OAuth app > Register an OAuth app in BankSync, generate public or confidential client credentials, manage redirect URIs, and rotate secrets. > Source: https://banksync.io/docs/api/registering-an-app An OAuth app lets a product connect to BankSync on behalf of a user through the standard OAuth 2.1 authorization-code flow, rather than a copy-pasted API key. You register the **app** once (its name, branding, and the scopes it may request), then create one or more **client credentials** under it — a `client_id`, and for confidential clients a `client_secret`. This is the same model as GitHub Apps or Slack apps. [![Registering an OAuth app: the Apps list in the Developer section, the registration dialog with name, slug, tagline and scopes, uploading a logo, submitting for review, the verified badge, rotating client credentials to reveal the one-time bscs\_ secret, and the connected apps your users see.](https://cdn.banksync.io/videos/oauth-app-registration.poster.02caa98794761883.png)](https://cdn.banksync.io/videos/oauth-app-registration.eabbd11c31d55d9f.mp4) [Watch: Registering an OAuth app: the Apps list in the Developer section, the registration dialog with name, slug, tagline and scopes, uploading a logo, submitting for review, the verified badge, rotating client credentials to reveal the one-time bscs\_ secret, and the connected apps your users see.](https://cdn.banksync.io/videos/oauth-app-registration.eabbd11c31d55d9f.mp4) > **Before you start:** You need the Admin or Owner role in the workspace to register or manage apps. Apps you > register are internal to your workspace until you request verification — they work for your own > workspace with no review. ## App vs client - An **app** is the product a user sees on the consent screen: name, logo, description, and verification status. - A **client** is a set of credentials your software authenticates with. One app can have several clients — for example separate `dev`, `staging`, and `prod` credentials. ## Register an app **Register an app** 1. **Open Developer settings** — Click your workspace menu, then select Developers, and open the Apps tab. 2. **Start a new app** — Click Create app. The dialog asks for the name, slug, a tagline and description, a category, optional tags, and the scopes your app needs. 3. **Name the app** — Enter a Name (shown on the consent screen) and a Slug — lowercase letters, numbers, and hyphens, unique across BankSync. The slug is suggested from the name; edit it if you like. 4. **Describe it** — Add a Tagline (a one-line summary shown on cards and the consent header), a longer Description, and optional Tags. You can edit all of these later on the Details tab. 5. **Choose scopes** — Under Scopes, toggle the read and write permissions your app needs per resource. Request the least you need — the user reviews these when they authorize your app, and can downgrade them. 6. **Create it** — Click Create app. You land on the app's detail page, where you add client credentials and branding. ## Create client credentials **Create a client** 1. **Open the Credentials tab** — On the app detail page, open Credentials and click New client. 2. **Choose a client type** — Pick Confidential for a backend service that can keep a secret, or Public (PKCE) for a native app or SPA that cannot. Public clients use PKCE and have no secret. 3. **Add redirect URIs** — Enter one or more exact redirect URIs the authorization server will redirect back to. They must match exactly at authorization time. 4. **Create the client** — Click Create client. For a confidential client, the client secret is shown once — copy it now and store it securely. BankSync only keeps a hash and the last four characters; the secret cannot be retrieved again. > **The secret is shown once:** A confidential client's secret appears exactly once, at creation and after each rotation. If you > lose it, rotate the secret to get a new one. ## Rotate a secret Rotating replaces a client's secret with a new one and shows it once. The **previous secret keeps working for 7 days** so you can roll it out to your servers without downtime. After the grace period the old secret returns `invalid_client`. To rotate, open the client on the **Credentials** tab and click the rotate control, then copy the new secret. ## Manage redirect URIs Open a client's **Edit** control under Credentials to add or remove redirect URIs. Each must be a valid `https://` URL (loopback `http://localhost` is allowed for development). Changes take effect immediately. ## Delete an app or client Deleting a client revokes its active authorizations and refresh tokens. Deleting the whole app removes all of its clients and revokes every grant. Already-issued short-lived access tokens keep working until they expire (up to one hour). ## Next steps - [API keys](/docs/api/api-keys) — the simpler credential for scripts and CI that your workspace owns. - [Authentication](/docs/api/authentication) — how the OAuth 2.1 authorization-code + PKCE flow works end to end. - [MCP overview](/docs/mcp/overview) — connect AI tools to BankSync. --- # App branding & logo > Add a logo, homepage, privacy policy, terms, and support email to your OAuth app so it looks trustworthy on the BankSync consent screen. > Source: https://banksync.io/docs/api/app-branding Your app's branding is what users see when they authorize it on the BankSync consent screen: the logo, the display name, and links to your homepage, privacy policy, and terms. Complete branding makes your app look trustworthy — and it's required before you can request verification. > **Before you start:** You need the Admin or Owner role in the workspace that owns the app. Branding is optional > while an app is internal (draft), and required when you request verification. [![An OAuth app's branding and verification: adding a logo and details, requesting verification, the verified badge on the app, and how a verified app shows your brand on the consent screen.](https://cdn.banksync.io/videos/app-branding.poster.b6ac7a7bb0260ceb.png)](https://cdn.banksync.io/videos/app-branding.a97f24f44bf1e82f.mp4) [Watch: An OAuth app's branding and verification: adding a logo and details, requesting verification, the verified badge on the app, and how a verified app shows your brand on the consent screen.](https://cdn.banksync.io/videos/app-branding.a97f24f44bf1e82f.mp4) ## Upload a logo **Upload a logo** 1. **Open the Branding tab** — On the app detail page (Developers → Apps → your app), open the Branding tab. 2. **Choose an image** — Click Upload (or drag an image onto the logo box). Use a PNG, JPEG, or WebP up to 1 MB. Square images look best. 3. **Done** — The logo uploads and appears immediately. Click Replace to change it or Remove to clear it. > **Supported formats:** Logos must be static raster images — PNG, JPEG, or WebP. SVG isn't accepted. Images are downscaled > to a square thumbnail before upload. ## Add details On the **Details** tab you also control the text users see on the consent screen: - **Tagline** — a one-line summary, shown on your app's card and the consent header. - **Description** — a longer description shown in full when a user authorizes your app. - **Tags** — up to six comma-separated keywords (for example `reporting, ai`). ## Set your links On the same **Details** tab, fill in: - **Homepage URL** — where users can learn about your app. - **Privacy policy URL** — how you handle their data. - **Terms of service URL** — optional. - **Support email** — where users can reach you. Click **Save** to persist the changes. Each URL must be a valid `https://` link. ## Where branding appears The logo, name, and links show on the **consent screen** every time a user authorizes your app. A complete, professional presentation reduces drop-off and is a prerequisite for the **Verified** badge. ## Next steps - [Register an OAuth app](/docs/api/registering-an-app) — create the app and its client credentials. - Once branding is complete, request verification from the app's **Overview** tab. --- # Portals & Cross-Workspace Queries > Manage multiple client portals from one parent workspace. Query banks, feeds, integrations, and jobs across all portals with the scope=family parameter. > Source: https://banksync.io/docs/api/portals If you're an accountant managing multiple clients, BankSync lets you organise each client into a Portal: a dedicated workspace they own, billed to you. This guide explains how to query data across your portals programmatically with the `scope=family` parameter. ## What's a portal? A portal is a child workspace under your parent workspace. Each portal has its own: - Bank connections (the client's own, isolated from yours) - Members (the client themselves, plus anyone they invite if you allow it) - Feeds, integrations, jobs - Soft-delete + 30-day cleanup lifecycle Your portals roll up to your plan: one Stripe subscription pays for the parent and every portal under it. The parent's owner and admins have implicit owner / admin authority on every portal, no separate invitation needed. > **Who can use cross-workspace queries** > > Family-scoped reads require **admin** or **owner** role on the parent workspace. Portal-direct members (clients you've invited) cannot use them: they only see their own portal's data. ## The `scope` query parameter Every list endpoint accepts an optional `scope` query parameter that controls what set of workspaces the query operates over. | Value | Returns | Requires | | ---------------- | -------------------------------------------------------------------------------------- | ------------------------------------- | | `self` (default) | Just this workspace's rows | The endpoint's standard role | | `family` | This workspace + every live portal under it. Each row gains `workspaceId` and `portal` | **Admin+**, top-level workspaces only | Endpoints supporting `scope=family` today: - `GET /v1/banks` - `GET /v1/feeds` - `GET /v1/integrations` - `GET /v1/jobs` (internal API only for now) ## Example: list every bank across all your portals Your parent-workspace API key works for this: no need to mint a separate key per portal. ```bash curl -X GET "https://api.banksync.io/v1/banks?scope=family" \ -H "X-API-Key: bsk_your_api_key_here" \ -H "Content-Type: application/json" ``` ```javascript const response = await fetch('https://api.banksync.io/v1/banks?scope=family', { headers: { 'X-API-Key': process.env.BANKSYNC_API_KEY, 'Content-Type': 'application/json', }, }) const { data: banks } = await response.json() for (const bank of banks) { if (bank.portal) { console.log(`${bank.name} - ${bank.portal.name}`) } else { console.log(`${bank.name} - (my workspace)`) } } ``` ```python import os import requests response = requests.get( "https://api.banksync.io/v1/banks?scope=family", headers={ "X-API-Key": os.environ["BANKSYNC_API_KEY"], "Content-Type": "application/json", }, ) for bank in response.json()["data"]: where = bank["portal"]["name"] if bank.get("portal") else "(my workspace)" print(f"{bank['name']} - {where}") ``` ### Response shape Each row gains two fields when `scope=family` is requested: ```json { "success": true, "data": [ { "id": "bnk_abc", "name": "Chase Checking", "workspaceId": "ws_parent", "portal": null, ... }, { "id": "bnk_xyz", "name": "Acme Co Operating", "workspaceId": "ws_acme_portal", "portal": { "id": "ws_acme_portal", "name": "Acme Co", "icon": "🏢" }, ... } ] } ``` - `workspaceId`: the workspace the row actually lives in. For your own rows this is the parent workspace; for portal rows this is the portal's id. - `portal`: attribution badge. `null` for rows owned by the parent; a `{ id, name, icon? }` object for rows owned by a portal. ## Targeting a single portal Portals are workspaces: you can address one directly via its workspace id. Your parent-scoped API key is automatically authorised against every live portal you own; no per-portal key needed. ```bash # List banks in one specific client's portal curl -X GET "https://api.banksync.io/v1/banks" \ -H "X-API-Key: bsk_your_api_key_here" \ -H "X-Workspace-Id: ws_acme_portal" # Or use the workspace id in the URL path (depending on the endpoint). ``` The credential still has to come from your parent workspace (or be a Firebase session). A key minted on workspace A cannot reach into workspace B's portals, only into A's own. ## Error responses | Status | When | | ------ | -------------------------------------------------------------------------------------------------------------------- | | `400` | Unknown `scope` value (anything other than `self` / `family`), or `scope=family` was sent against a portal workspace | | `403` | Your role on the parent workspace is editor or viewer: `scope=family` requires admin+ | | `404` | The workspace id in the URL doesn't exist or was deleted | ## Using portals with MCP Connect an MCP client (Claude Code, Cursor, etc.) to your parent workspace once: your portals appear automatically. - `list_workspaces` surfaces every portal you manage with `isInherited: true` and a `parentWorkspaceId`. - All workspace-scoped tools (`list_banks`, `list_feeds`, …) accept any portal's `workspaceId` you own. - See the [MCP setup guide](/docs/mcp/connect-an-agent) for connecting your client. > **For clients, not advisors** > > If you've been invited into a portal by an accounting firm, programmatic access is intentionally not available: your accountant manages API keys and MCP connections on your behalf. The portal Developer Settings tab is hidden for portal-direct members. ## Internal API vs public REST API Two surfaces ship the same `scope=family` contract: - **Public REST API** (`api.banksync.io/v1/*`): the surface most third-party integrations use. Banks, feeds, integrations all accept `?scope=family`. - **Internal API** (`internal-api.banksync.io/api/*`): used by the BankSync web app and MCP server. Same scope semantics, plus a `/jobs` workspace-aggregate endpoint. ## See also - [Authentication](/docs/api/authentication): API keys, scopes, and bearer tokens - [API reference](/docs/api/reference): every endpoint and its response shape - [MCP setup](/docs/mcp/connect-an-agent): connect Claude Code or other MCP clients --- # Webhooks developer reference > The webhook payload contract: the signed envelope, event types, per-data-type field schemas, signature verification, retries, and idempotency. > Source: https://banksync.io/docs/api/webhooks-reference BankSync delivers synced bank data to your endpoint as signed JSON POST requests. This reference documents the wire format so you can build and verify a receiver. To connect an endpoint and create a feed, see the [Webhooks integration guide](/docs/integrations/webhooks). [![The webhook destination this reference describes, set up in the app: entering the endpoint URL, revealing the whsec\_ signing secret shown once, a test delivery returning 200 in 142ms, and the recent deliveries table with status codes and attempts.](https://cdn.banksync.io/videos/webhook-destination-feed.poster.9f085924736e4b13.png)](https://cdn.banksync.io/videos/webhook-destination-feed.b93e77b77369be96.mp4) [Watch: The webhook destination this reference describes, set up in the app: entering the endpoint URL, revealing the whsec\_ signing secret shown once, a test delivery returning 200 in 142ms, and the recent deliveries table with status codes and attempts.](https://cdn.banksync.io/videos/webhook-destination-feed.b93e77b77369be96.mp4) ## The envelope Every delivery is a single JSON object: ```json { "id": "evt_job-abc_0_1_2", "type": "transactions.delta", "apiVersion": "2026-06-01", "createdAt": "2026-06-01T09:30:00.000Z", "workspaceId": "ws_...", "feed": { "id": "feed_...", "name": "Chase to Webhook", "dataType": "transactions" }, "job": { "id": "job_abc", "trigger": "scheduled" }, "batch": { "sequence": 3 }, "data": [ /* rows: see the per-type schemas below */ ] } ``` | Field | Type | Notes | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Unique per delivery. **Your idempotency key.** Stable across retries and replays. Matches the `webhook-id` header. | | `type` | string | The event type (see below). | | `apiVersion` | string | Date-pinned payload contract version. Currently `2026-06-01`. New fields may be added without bumping it; a breaking change bumps it. | | `createdAt` | string | ISO 8601 timestamp the event was built. | | `workspaceId` | string | Your BankSync workspace id. | | `feed` | object | `{ id, name, dataType }` of the feed that produced the event. Absent on `endpoint.test`. | | `job` | object | `{ id, trigger }`. `trigger` is `scheduled` \| `manual` \| `api` \| `test` \| `redelivery`. | | `batch` | object | `{ sequence }`, the 1-based ordinal of this batch within the job, per feed. Present on data events. | | `data` | array | The rows. Present on data + test events. | ## Event types | Type | When | Semantics | | -------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `transactions.delta` | transactions feed, each run | New or updated transactions since the last run. **Upsert by `data[].id`.** | | `balances.snapshot` | balances feed, each run | Current balance per account. Replace state keyed by `accountId`. | | `holdings.snapshot` | holdings feed, each run | Current holdings. Replace state keyed by `accountId` + `ticker`. | | `trades.snapshot` | trades feed, each run | Current trades. Replace state keyed by `id`. | | `orders.snapshot` | orders feed, each run | Open/pending brokerage orders. Replace the set keyed by `id`. | | `loans.snapshot` | loans feed, each run | Current loan state. Replace keyed by `id`/`accountId`. | | `sync.completed` | end of a job | Terminal summary: `{ status, rowsDelivered, batchesDelivered }`. The signal that a snapshot is complete; commit your swap here. | | `sync.failed` | a job failed | Same summary shape with `status: "failed"` and an `errorCategory`. | | `endpoint.test` | "Send test event" | Sample rows for a chosen data type. Marked `"test": true` in the envelope. | > **Delta vs snapshot:** 'Transactions are deltas: each event carries only new or changed rows, which you upsert by id. Every other type is a snapshot: each run sends the full current state, batched across one or more events, ending with sync.completed.' ## Signing & verification BankSync signs every delivery using the [Standard Webhooks](https://www.standardwebhooks.com) format, so existing verifier libraries work out of the box. Each request carries: ``` webhook-id: evt_job-abc_0_1_2 webhook-timestamp: 1718270000 webhook-signature: v1,g0Q1...base64...== content-type: application/json user-agent: BankSync-Webhooks/1.0 (+https://banksync.io/docs/api/webhooks-reference) ``` The signature is `HMAC-SHA256` over the string `{webhook-id}.{webhook-timestamp}.{body}`, base64-encoded, keyed by the base64-decoded payload of your `whsec_` secret. During a secret rotation the header carries two space-separated signatures (current + previous); a delivery is valid if **either** verifies. > **Reject stale timestamps:** 'To prevent replay, reject any request whose webhook-timestamp is more than 5 minutes from now before processing it.' Verify with the Standard Webhooks library for your language: ```js // Node (npm i standardwebhooks) import { Webhook } from 'standardwebhooks' const wh = new Webhook(process.env.BANKSYNC_WEBHOOK_SECRET) // "whsec_..." app.post('/webhooks/banksync', express.raw({ type: 'application/json' }), (req, res) => { let event try { event = wh.verify(req.body, { 'webhook-id': req.header('webhook-id'), 'webhook-timestamp': req.header('webhook-timestamp'), 'webhook-signature': req.header('webhook-signature'), }) } catch { return res.sendStatus(400) // bad signature } // De-dupe on event.id, then process event.data … res.sendStatus(200) }) ``` ```python # Python (pip install standardwebhooks) from standardwebhooks import Webhook wh = Webhook(os.environ["BANKSYNC_WEBHOOK_SECRET"]) # "whsec_..." @app.post("/webhooks/banksync") def banksync_webhook(): try: event = wh.verify(request.data, dict(request.headers)) except Exception: return ("", 400) # De-dupe on event["id"], then process event["data"] … return ("", 200) ``` Respond with any `2xx` to acknowledge. Non-2xx responses are retried (see below). ## Retries & delivery Delivery is **at-least-once**. BankSync retries transient failures with exponential backoff: | Response | Behavior | | ----------------------------- | -------------------------------------------------------------------- | | `2xx` | Success. | | `408`, `425`, `429`, `5xx` | Retried with backoff. `429` honors `Retry-After` (capped at 10 min). | | network error / timeout (30s) | Retried with backoff. | | `410 Gone` | The endpoint is treated as unsubscribed and **disabled**. | | other `4xx`, and any `3xx` | Permanent rejection, not retried. Redirects are never followed. | Because delivery is at-least-once and retries reuse the same `id`, **deduplicate on `id`** (or `webhook-id`). Within a job, `batch.sequence` lets you order batches. An endpoint that fails persistently is auto-disabled; re-enable it from the endpoint page after fixing your server. ## Per-data-type payloads Rows are camelCase; money is JSON numbers (parse with a decimal type); dates are ISO 8601 (or `YYYY-MM-DD` for date-only fields); currency is ISO 4217. Optional fields are omitted when absent. Enrichment-added custom fields are nested under a `custom` object. Field availability varies by provider (Plaid / Fiskil / SaltEdge / SnapTrade). ### transactions.delta | Field | Type | Notes | | ---------------------------------------------------------- | --------- | --------------------------------------------------------- | | `id` | string | Stable per provider. Upsert key. | | `date` | string | Posted date/time. | | `authorizedDate` | string? | Authorization date. Absent for SaltEdge. | | `description` | string | Merchant/description. | | `merchantName` | string? | Cleaned merchant name (provider enrichment). | | `originalDescription` | string? | Raw statement text. Plaid only. | | `amount` | number | Signed; **positive = money in**. | | `creditAmount` / `debitAmount` | number | Unsigned split (one is 0). | | `currency` | string | ISO 4217. | | `category` | string? | | | `type` | string? | debit / credit / transfer / fee. | | `reference` | string? | | | `pending` | boolean | | | `pendingTransactionId` | string? | Plaid posted rows reference the pending row they replace. | | `accountId`, `accountName`, `accountNumber`, `accountType` | string(?) | Account identity. | | `bankId`, `bank` | string(?) | Bank identity. | | `custom` | object? | Enrichment-added fields. | ### balances.snapshot | Field | Type | Notes | | ---------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------- | | `date` | string | Snapshot time (not a bank timestamp). | | `amount` | number | Ledger balance. | | `availableBalance` | number? | Spendable now; available credit for cards. Omitted for SnapTrade. | | `pendingBalance` | number? | `max(0, amount - availableBalance)`. | | `creditLimit` | number? | Credit products only. | | `currency` | string | | | `accountId`, `accountName`, `accountNumber`, `accountType`, `bankId`, `bank` | string(?) | | ### holdings.snapshot | Field | Type | Notes | | ------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------- | | `id` | string? | Synthesized per account + security. | | `security`, `ticker` | string? | | | `quantity` | number | | | `price`, `priceDate`, `currentValue` | number?/string? | | | `costBasis` | number? \| null | `null` = brokerage didn't report it. | | `isCashEquivalent` | boolean? | Cash arrives as a holding with `ticker: "CUR:USD"`, `price: 1`. Don't double-count against a balances feed. | | `currency` | string | | | account/bank identity fields | string(?) | | ### trades.snapshot | Field | Type | Notes | | ---------------------------- | --------- | ----------------------------------------------------------------------------------- | | `id`, `date` | string | | | `type` | string | buy / sell / dividend / fee. | | `amount` | number | Signed; **positive = cash out** (a buy). Note this is the opposite of transactions. | | `quantity`, `price`, `fees` | number? | | | `security`, `ticker` | string? | | | `currency` | string | | | account/bank identity fields | string(?) | | ### orders.snapshot | Field | Type | Notes | | --------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------- | | `id` | string | Namespaced `order:` so it never collides with a trade id. | | `brokerageOrderId`, `date`, `status`, `action`, `orderType` | string | | | `timeInForce` | string? | | | `totalQuantity`, `filledQuantity`, `openQuantity`, `canceledQuantity` | number? | | | `limitPrice`, `stopPrice`, `executionPrice` | number? | | | `executedAt`, `expiresAt` | string? | | | `security`, `ticker`, `currency` | string(?) | | | account/bank identity fields | string(?) | | ### loans.snapshot The widest schema; almost every field is optional and provider/product-dependent. Core fields: `id`, `accountId`, `loanType`, `loanName`, `currentBalance`, `originalAmount`, `interestRate`, `minimumPaymentAmount`, `nextPaymentDueDate`, `isOverdue`, `currency`, `bankId`. Product-specific groups: - **Credit cards:** `aprPurchase`, `aprCash`, `aprBalanceTransfer`, `lastStatementBalance`, `lastStatementDate`. - **Student loans:** `disbursementDates` (array), `pslfStatus`, `repaymentPlan`. - **Mortgages:** `escrowBalance`, `hasPMI`, `hasPrepaymentPenalty`, `propertyAddress` (object), `loanTerm`, `maturityDate`. ## Idempotency & ordering checklist - Deduplicate on `id`. - For `transactions.delta`, upsert by `data[].id`. - For snapshots, replace state by the documented identity key when `sync.completed` arrives. - Reject `webhook-timestamp` older than 5 minutes. - Don't require auth on the receiving route; verify the signature instead. --- # Ask Penny > Ask Penny questions about your synced financial data in plain language, get insight charts inline, and let Penny build dashboards and configure feeds for you. > Source: https://banksync.io/docs/ask-penny/ask-penny **Ask Penny** is the in-app assistant that answers questions about your workspace's data, renders charts and KPIs inline in the chat, and can drive the app for you, building dashboards and helping configure feeds. Open Penny from the top header; she docks to either edge and coexists with whatever you already have open. [![Ask Penny walkthrough](https://cdn.banksync.io/videos/ai-copilot.poster.38f2d3d551c0da46.png)](https://cdn.banksync.io/videos/ai-copilot.fde43395aac13b66.mp4) [Watch: Ask Penny walkthrough](https://cdn.banksync.io/videos/ai-copilot.fde43395aac13b66.mp4) > **Plan availability:** Ask Penny is included on Standard plans and above. On Free and Starter plans you'll see an upgrade prompt that routes you to the cheapest plan that unlocks her. ## Asking questions Type a question in plain language, for example "What did I spend at restaurants last month?" or "Why is one of my feeds empty?". Penny reads your workspace's connected banks, feeds, and dashboards to answer, and the response streams in token-by-token with any tool activity (like reading transactions) shown as it runs. Your conversations are saved per workspace and are private to you. You can rename or delete any conversation from the thread list, and start a new one at any time. If you stop a response mid-stream or navigate away, the turn ends cleanly and the partial answer is saved. ## Insight widgets When you ask for an insight, Penny doesn't just describe it. She renders a real chart, KPI, or table inline in the chat, built from your data. - **Rendered inline** — Charts and KPIs appear directly in the conversation, not as a description you have to recreate. - **Add to a dashboard** — Keep any proposed insight with one click. It's added to a dashboard so you can return to it later. ## Choosing a model By default Penny is set to **Auto**, which picks a sensible model for each question. You can also pick a specific model from the composer; each option shows its relative credit cost so you can trade speed against depth. ## Credits and usage Ask Penny usage is metered in credits. Each plan includes a monthly allotment, and you can see your remaining balance and buy more from the credit meter at any time. - **Monthly allotment** — Your plan's included credits refresh each month. Use them or lose them. - **Top-up packs** — Buy a one-time credit pack at any time. Purchased credits never expire and roll over. If you run out mid-conversation, Penny stops cleanly at a safe point and prompts you to top up rather than failing partway through an answer. ## Bring your own key (Pro and Business) On Pro and Business plans you can add your own AI provider API key. When a key is present, your conversations run on your provider account and cost **zero** BankSync credits. > **Your key stays private:** Your provider key is encrypted at rest and never leaves BankSync's servers. You only ever see the last four characters. If a stored key is rejected (for example, you rotated it at your provider), Penny shows a clear prompt to re-enter it, and the turn is never silently charged credits. You can add or remove a key at any time from the key settings (the key icon in Ask Penny). ## Confirmation before changes When you ask Penny to take an action that changes something, she asks you to confirm first, so nothing happens to your workspace without your say-so. --- # Creating Your First Feed > Step-by-step guide to setting up your first data feed from bank accounts to Google Sheets, Notion, or Airtable. > Source: https://banksync.io/docs/bank-feeds/creating-first-feed Once you've connected a bank and an integration, you're ready to create your first feed. A feed defines one flow of data: which accounts it reads from, which integration it writes to, how fields map to columns, and how often it runs. This guide walks you through the four setup steps. > **Prerequisites:** 'Before creating a feed, make sure you have:\n• Connected at least one bank (Banks tab → Add Bank)\n• Set up at least one integration (Integrations tab), such as Google Sheets, Excel, Notion, Airtable, or a database' [![The complete first-feed setup: choosing Bank Sync as the source, selecting a Chase account, picking a Notion database as the destination, mapping the amount, date and description fields, setting a daily schedule, and triggering the first sync.](https://cdn.banksync.io/videos/create-feed-and-sync.poster.d4c039ebcdad5076.png)](https://cdn.banksync.io/videos/create-feed-and-sync.1b927dcf6b8418b4.mp4) [Watch: The complete first-feed setup: choosing Bank Sync as the source, selecting a Chase account, picking a Notion database as the destination, mapping the amount, date and description fields, setting a daily schedule, and triggering the first sync.](https://cdn.banksync.io/videos/create-feed-and-sync.1b927dcf6b8418b4.mp4) ## The Four Setup Steps The feed editor has an **Overview** tab plus four configuration tabs, one per step. Your progress is automatically saved as you go, so you can leave and come back any time. - **1. Sources** — Select bank accounts to pull data from - **2. Destination** — Choose which integration receives the data - **3. Mapping** — Map data fields to columns - **4. Schedule** — Set up automatic syncing (optional) ## Step 1: Sources In the **Sources** tab, select which bank accounts you want to pull data from. **Selecting Your Accounts** 1. **Browse your connected banks** — Your connected banks are listed with their accounts underneath. Each account shows its type as a badge (Checking, Savings, Credit Card, etc.). 2. **Check the accounts to include** — Click the checkboxes next to accounts you want in this feed. You can select accounts from multiple banks in one feed. 3. **Choose the feed type** — Each feed carries one data type. The type is auto-detected based on your accounts, but you can change it. - **Transactions** — Individual transaction records - **Balances** — Account balance snapshots - **Trades** — Investment transactions - **Holdings** — Portfolio positions Loans (liability balances) and Orders (open brokerage orders) are also available as feed types when your selected accounts support them. One feed carries exactly one data type, so create separate feeds to sync, say, transactions and balances from the same accounts. > **Account Type Restriction:** 'Investment accounts cannot be mixed with checking/savings accounts in the same feed. Create separate feeds for different account types.' ## Step 2: Destination In the **Destination** tab, choose which integration receives the data, then pick the exact place inside it. ### Google Sheets 1. **Select a spreadsheet** — Choose from spreadsheets in your connected Google account. 2. **Choose a sheet** — Select the specific sheet within the spreadsheet. 3. **Set header row** — Specify which row contains your column headers (default: row 1). 4. **Choose direction and position** — Select by row (most common) or by column, and whether to add data at the beginning or end. ### Notion 1. **Select a workspace** — Choose from workspaces shared with BankSync. 2. **Choose a database** — Select the database where data will be added. > **Share the database with the BankSync connection:** 'A Notion database only appears in the picker if the BankSync connection has been added to it. In Notion, open the database, click the ••• menu → Connections, and add BankSync. Without the connection, BankSync cannot read or write that database, and the search shows "No databases found".' ### Airtable 1. **Select a base** — Choose from bases in your connected Airtable account. 2. **Choose a table** — Select the table within the base. > **Quick Add:** Don't see the integration you need? You can connect another integration without leaving the feed setup, or manage them all from the Integrations tab. ## Step 3: Mapping In the **Mapping** tab, map your bank data fields to the columns in your sheet or table using drag-and-drop. ### Available Transaction Fields - **ID** — Unique transaction identifier - **Date** — Transaction date - **Description** — Merchant or transaction name - **Credit Amount** — Money coming in - **Debit Amount** — Money going out - **Category** — Transaction category - **Type** — Transaction type - **Bank** — Source bank name - **Account** — Account name ### How to Map Fields 1. **Drag and drop to reorder** — Arrange fields in your preferred order by dragging them in the mapping list. 2. **Pick a column for each field** — Use the dropdown next to each field to map it to a column in your sheet or table. 3. **Remove unwanted fields** — Click the X button to remove fields you don't need. 4. **Add additional fields** — Drag fields from the available pool to add them to your mapping. For the full mapping reference, including Auto fill, see [Configuring Field Mappings](/docs/bank-feeds/field-mappings). ### Balance Sync Mode When syncing balances, choose how data should be handled: - **Append** — Adds a new timestamped row each sync, building balance history over time - **Overwrite** — Updates the same rows in place, keeping only the current state (for dashboards) ## Step 4: Schedule (Optional) In the **Schedule** tab, set up automatic syncing on a recurring schedule. This step is optional; you can always run feeds manually. - **Hourly** — Run about once an hour - **Daily** — Run every day at a set time - **Weekly** — Run on a specific day of the week - **Manual** — No schedule; run only when you click Sync Now > **Time Zone and Plan Gating:** 'You pick the run hour in your own time zone (shown next to the picker); runs happen at the top of the hour. Available cadences depend on your plan: Free and Starter allow Weekly, Standard adds Daily, and Professional and above unlock Hourly. See the scheduling guide for details.' ## Confirm your setup When all four steps are done, the feed editor's **At a glance** panel summarizes the feed. Every row (From, To, Mapping, Schedule) should show a real value, not "Not configured". If a row still says "Configure", open that tab and finish it. ![The feed editor At a glance panel: From Chase, To Sheets, Mapping 8 fields, Schedule Daily, each with an edit link](https://cdn.banksync.io/screenshots/feeds/sync-at-a-glance.9ab0f122dcacd92a.png "A fully configured sync feed at a glance") ## Running Your Feed Once configured, click your feed card in the Feeds tab and then "Run" to start syncing data. ### Run Options - **Incremental (Default)** — Fetches only what's new since your last sync. BankSync tracks progress per account so nothing is missed or duplicated. - **Start from the beginning** — An optional checkbox in the Sync Now dialog that re-fetches all available data from scratch. Use it sparingly: re-syncing data that was already written can create duplicate rows. Manual runs use the same read path and deduplication as scheduled syncs, so running "Sync Now" alongside a schedule never creates duplicates. ### Monitoring Progress - Click "History" to see all sync jobs (past and in-progress) - Job status updates in real-time: Created → In Progress → Completed - View error details if a sync fails, with remediation suggestions > **Pro Tips:** '• Check the result: After your first run, open your spreadsheet or database to verify the data looks correct before enabling a schedule.\n• Create multiple feeds: Many users have separate feeds for transactions (daily) and balances (weekly).' ## Related guides - [Configuring Field Mappings](/docs/bank-feeds/field-mappings): everything about the Mapping tab, including Auto fill - [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds): cadences, local-time scheduling, and plan gating - [Managing Your Feeds](/docs/bank-feeds/managing-feeds): editing, running, and monitoring feeds after setup - [Managing Integrations](/docs/integrations/managing-integrations): connect and maintain the integrations feeds write to [Managing your feeds](/docs/bank-feeds/managing-feeds) --- # How to Sync Balance Data > Learn how to set up balance feeds to track your account balances over time in Notion, Google Sheets, or Airtable. > Source: https://banksync.io/docs/bank-feeds/sync-balances Balance feeds track your account balances over time. Build net worth dashboards, monitor cash flow, and maintain a historical record of your financial position. [Video: SYNC Bank Balances to Google Sheets](https://www.youtube.com/watch?v=Id-ZV3VVc9Q) - **Current Balance** — Point-in-time account balance snapshots - **Historical Tracking** — Track balance changes over time - **Multiple Accounts** — Monitor all accounts in one place [![Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.poster.aab068ddd35cd6f7.png)](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) [Watch: Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) ## Balance Data Fields - **Current Balance** — The account's current balance - **Available Balance** — Funds available to spend - **Account Name** — Account identifier - **As Of Date** — Balance snapshot date - **Currency** — Account currency - **Account Type** — Checking, savings, etc. ## Append vs. Overwrite Balances are point-in-time values, not a history your bank stores for you. Each sync captures the balance as it is right now, and the sync mode you pick in the **Mapping** tab decides what happens to that value in your sheet or table: - **Append** — Adds a new timestamped row each sync, one per account. Your history builds up sync by sync, so this is how you get balance-over-time charts. - **Overwrite** — Updates the same rows in place, keeping only the latest balance for each account. Best for dashboards that show current state only. > **History starts when the feed starts:** Unlike transactions, balances can't be backfilled: banks report the current balance, not what it was last March. Your first sync writes today's balance, and history accumulates from there. If you want a long-term record, set up an Append feed sooner rather than later. ![The Mapping tab for a balances feed writing to Google Sheets, showing the balance mode selection cards: Append, which adds a new timestamped row each sync, selected, and Overwrite, which updates the same rows in place.](https://cdn.banksync.io/screenshots/feeds/balance-modes.b9a90a6cedba53a9.png "Choose Append for balance history or Overwrite for a current-state dashboard.") ## Setting Up a Balance Feed **Setup Steps** 1. **Connect your bank** — Ensure the bank account is connected in the Banks tab. 2. **Create a balance feed** — Click Create Feed and select 'Balances' as the feed type in the Sources tab. 3. **Select accounts** — Choose which accounts to track balances for. You can include accounts from multiple banks in one feed. 4. **Pick an integration** — In the Destination tab, choose which integration receives the data, then map balance fields to the columns in your sheet or table. 5. **Choose Append or Overwrite** — Select Append for history or Overwrite for a current-state view. 6. **Configure schedule** — Set how often to capture balances. Daily is the sweet spot for net worth tracking; note that Daily requires the Standard plan or higher (see the scheduling guide). ## What happens on each sync - **First sync**: one balance value is written per selected account. - **Subsequent syncs**: in Append mode, a new row per account is added each run; in Overwrite mode, each account's existing row is updated in place. - **Cadence determines granularity**: a weekly Append feed produces one data point per account per week. You can't fill the gaps later, so pick the cadence that matches the resolution you want. ## Common Use Cases - **Net Worth Tracking** — Sum all account balances to track total net worth over time - **Cash Flow Monitoring** — Watch checking account balances to manage cash flow - **Financial Dashboard** — Build a central dashboard showing all account balances > **Daily Append snapshots:** 'For net worth tracking, use a daily schedule with Append mode. This creates a historical record you can chart to visualize your financial progress over weeks, months, and years.' ## Common pitfalls - **Picking Overwrite when you wanted history**: Overwrite keeps only the latest value. If your chart only ever shows one point per account, switch the feed to Append. - **Editing Append rows manually**: the feed adds rows below (or alongside) existing data; reordering or deleting synced rows in your sheet can make the history confusing. Do analysis in a separate tab that references the synced sheet. - **Including loan accounts**: liabilities have their own feed type with loan-specific fields. See [How to Sync Loan Data](/docs/bank-feeds/sync-loans). ## Related guides - [How to Sync Loan Data](/docs/bank-feeds/sync-loans): track liability balances for the other half of net worth - [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds): cadence options, UTC timing, and which plans get Daily and Hourly - [Configuring Field Mappings](/docs/bank-feeds/field-mappings): full reference for the Mapping tab, including Append and Overwrite - [Creating Your First Feed](/docs/bank-feeds/creating-first-feed): the end-to-end feed setup walkthrough [Create Your First Feed](/docs/bank-feeds/creating-first-feed) --- # How to Sync Holdings Data > Learn how to set up holdings feeds to track your investment portfolio positions and values. > Source: https://banksync.io/docs/bank-feeds/sync-holdings Holdings feeds track your current investment positions. Monitor your portfolio composition, track position values, and build investment dashboards that update automatically. - **Portfolio Positions** — All securities you own - **Market Values** — Current position values - **Scheduled Updates** — Track value changes over time [![Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.poster.aab068ddd35cd6f7.png)](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) [Watch: Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) ## Holdings Data Fields - **Symbol** — Stock or fund ticker - **Security Name** — Full security name - **Quantity** — Shares or units held - **Price** — Current price - **Market Value** — Total position value - **Cost Basis** — Original purchase cost - **Gain/Loss** — Unrealized P\&L - **Account** — Brokerage account > **Field availability varies by brokerage:** Cost basis and gain/loss depend on what your brokerage reports. Some institutions don't provide cost basis for transferred-in positions, so those fields can be empty for specific holdings. ## Append vs. Overwrite Holdings are a point-in-time picture of your portfolio: each sync captures your positions as they are right now. The sync mode decides how that picture lands in your sheet or table: - **Append** — Writes a new timestamped set of rows (one per position) each sync. Use this to track how your portfolio composition and values change over time. - **Overwrite** — Updates the existing rows in place with current values. Best for live portfolio dashboards that should always show the present state. Like balances, holdings history can't be backfilled: your record starts from the first sync and accumulates with each scheduled run, so the cadence you pick determines the resolution of your history. ## Setting Up a Holdings Feed **Setup Steps** 1. **Connect your brokerage** — Ensure your investment account is connected in the Banks tab. Brokerages connect through the same flow as banks; see Connecting Brokerages if yours isn't linked yet. 2. **Create a holdings feed** — Click Create Feed and select 'Holdings' as the feed type in the Sources tab. 3. **Select investment accounts** — Choose which brokerage accounts to track. Investment accounts can't be mixed with checking/savings accounts in the same feed. 4. **Choose Append or Overwrite** — Use Overwrite for dashboards, Append for historical tracking. 5. **Pick an integration and map fields** — In the Destination tab, choose which integration receives the data, then map holdings fields to the columns in your sheet or table. 6. **Set a schedule** — Daily is typical for portfolio tracking (requires the Standard plan or higher; see the scheduling guide for plan gating). ![The BankSync Connect Bank dialog searching for Schwab, showing brokerage result cards such as Charles Schwab, Fidelity, Robinhood, and Questrade, each with an Investment account-type tag and the SnapTrade provider.](https://cdn.banksync.io/screenshots/banks/connect-search-brokerage.f87f5fe68a9fcfdb.png "Holdings feeds read from brokerage connections, connected through SnapTrade.") ## What happens on each sync - **First sync**: one row per position is written for each selected account. - **Subsequent syncs**: Append adds a fresh set of position rows each run; Overwrite refreshes the existing rows. Positions you've fully sold stop appearing in new Append snapshots. - **Number of rows varies**: unlike balances (one row per account), a holdings sync writes one row per position, so a 30-position portfolio adds 30 rows per Append run. Factor that in when choosing your cadence. ## Common Use Cases - **Portfolio Dashboard** — A current view of all investment positions - **Asset Allocation** — Track diversification across asset classes - **Performance Tracking** — Monitor gains and losses over time > **Combine with Trades:** 'Use holdings feeds alongside trade feeds for a complete picture. Holdings shows your current positions, while trades shows how you got there.' ## Related guides - [How to Sync Trade Data](/docs/bank-feeds/sync-trades): the transaction-level complement to holdings snapshots - [Connecting Brokerages](/docs/connecting-banks/brokerages): link Fidelity, Schwab, and other investment accounts - [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds): cadences, UTC timing, and plan gating - [Configuring Field Mappings](/docs/bank-feeds/field-mappings): full reference for the Mapping tab, including Append and Overwrite [Sync Trade Data](/docs/bank-feeds/sync-trades) --- # How to Sync Loan Data > Learn how to set up loan feeds to track mortgage, auto loan, and other liability balances. > Source: https://banksync.io/docs/bank-feeds/sync-loans Loan feeds track your liability balances including mortgages, auto loans, student loans, and credit lines. Monitor your debt paydown progress and include liabilities in your net worth calculations. - **Mortgages** — Home loan balances - **Auto Loans** — Vehicle financing - **Student Loans** — Education debt - **Credit Lines** — HELOC and personal lines [![Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.poster.aab068ddd35cd6f7.png)](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) [Watch: Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) ## Loan Data Fields - **Balance** — Current loan balance - **Original Amount** — Initial loan amount - **Interest Rate** — Current APR - **Payment** — Monthly payment - **Due Date** — Next payment due - **Loan Type** — Mortgage, auto, etc. - **Lender** — Institution name - **Term End** — Loan maturity date > **Field availability varies by lender:** Lenders report different levels of detail. Balance is broadly available, but fields like interest rate, payment amount, or term end can be empty if the institution doesn't share them. ## Append vs. Overwrite Loan data is point-in-time, like balances: each sync captures the loan's state as it is right now, and history cannot be backfilled. Choose how each sync is written in the **Mapping** tab: - **Append** — Adds a new timestamped row per loan each sync. This is how you build a paydown history: a steady record of the balance shrinking sync after sync. - **Overwrite** — Updates the same rows in place, keeping only current values. Best for net worth dashboards that need current liability totals. ![The Mapping tab balance mode selection cards for a point-in-time feed: Append, which adds a new timestamped row each sync, selected, and Overwrite, which updates the same rows in place.](https://cdn.banksync.io/screenshots/feeds/balance-modes.b9a90a6cedba53a9.png "Loans use the same Append/Overwrite choice as balances: Append builds a paydown history.") ## Setting Up a Loan Feed **Setup Steps** 1. **Connect your lender** — Go to the Banks tab and connect the institution that holds your loan. 2. **Create a loan feed** — Click Create Feed and select 'Loans' as the feed type in the Sources tab. 3. **Select loan accounts** — Choose which loan accounts to track. 4. **Choose Append or Overwrite** — Use Append to track paydown progress over time, Overwrite for a current-state dashboard. 5. **Pick an integration and map fields** — In the Destination tab, choose which integration receives the data, then map loan fields to the columns in your sheet or table. 6. **Set a schedule** — Weekly usually matches how often loan balances change, and it is available on every plan. ## What happens on each sync - **First sync**: one row per selected loan is written with its current state. - **Subsequent syncs**: Append adds a fresh row per loan each run; Overwrite refreshes the existing rows. - **Cadence sets your history's resolution**: loan balances typically change once a month (when a payment posts), so a weekly Append feed captures every payment without cluttering your sheet. ## Common Use Cases - **Debt Payoff Tracking** — Visualize your debt reduction progress over time - **Net Worth Calculation** — Include liabilities in your complete financial picture - **Payment Scheduling** — Track due dates and payment amounts > **Paydown history with Append:** 'For debt payoff tracking, schedule weekly syncs with Append mode. The rows that land just after your payment date show the new balance, creating a satisfying visual record of your progress as balances decrease.' ## Related guides - [How to Sync Balance Data](/docs/bank-feeds/sync-balances): track asset balances for the other half of net worth - [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds): cadences, UTC timing, and plan gating - [Configuring Field Mappings](/docs/bank-feeds/field-mappings): full reference for the Mapping tab, including Append and Overwrite - [Connecting Banks](/docs/connecting-banks/connect-a-bank): link the institutions that hold your loans [Track Account Balances](/docs/bank-feeds/sync-balances) --- # How to Sync Trade Data > Learn how to set up trade feeds to sync your investment transactions from brokerage accounts. > Source: https://banksync.io/docs/bank-feeds/sync-trades Trade feeds sync your investment transactions including stock purchases, sales, dividends, and other brokerage activity. Track your trading history across multiple accounts. - **Buy & Sell Orders** — Track all equity trades - **Dividends** — Dividend payments received - **Transfers** — Deposits and withdrawals - **Options & More** — Complex trade types [![Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.poster.aab068ddd35cd6f7.png)](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) [Watch: Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) ## Trade Data Fields - **Trade Date** — When the trade executed - **Symbol** — Stock ticker symbol - **Type** — Buy, sell, dividend, etc. - **Quantity** — Number of shares - **Price** — Price per share - **Total** — Total trade value - **Fees** — Commission and fees - **Account** — Brokerage account ## Setting Up a Trade Feed **Setup Steps** 1. **Connect your brokerage** — Go to the Banks tab and connect your brokerage account (Fidelity, Schwab, etc.). 2. **Create a trade feed** — Click Create Feed and select 'Trades' as the feed type in the Sources tab. 3. **Select accounts** — Choose the investment accounts to sync trades from. Investment accounts can't be mixed with checking/savings accounts in the same feed. 4. **Pick an integration** — In the Destination tab, choose which integration receives the data (Google Sheets, Excel, Notion, Airtable, or a database). 5. **Map fields** — Configure which trade fields map to the columns in your sheet or table. 6. **Schedule or backfill** — Set a recurring schedule for ongoing activity. For history, use "Start from the beginning" in the Sync Now dialog on a fresh feed to pull in all available past trades. ![The BankSync bank connection dialog with a search field, showing brokerage institutions available to connect](https://cdn.banksync.io/screenshots/banks/connect-search-brokerage.f87f5fe68a9fcfdb.png "Brokerages connect from the same Banks tab search as banks") > **Brokerage Support:** 'Trade data is available for major brokerages including Fidelity, Charles Schwab, E\*TRADE, and Robinhood. Data availability (and how far back history goes) varies by institution.' ## How trade syncs behave - **First sync**: trades are event records like transactions, so they can be backfilled. On a new feed the first sync backfills available history; long backfills are processed in 7-day chunks (see [Managing Sync Jobs](/docs/bank-feeds/managing-sync-jobs)). - **Subsequent syncs**: incremental runs pick up new activity since the last sync. - **Deduplication**: each trade is keyed on the provider's unique identifier, so overlapping date ranges and manual re-runs don't create duplicate rows. - **One data type per feed**: trades, holdings, and balances are separate feed types. Pair a trade feed with a holdings feed if you want both activity and current positions. ## Common Use Cases - **Trade Journal** — Keep a detailed log of all investment decisions - **Tax Reporting** — Track cost basis and gains for tax preparation - **Performance Analysis** — Analyze trading patterns and results ## Related guides - [Connecting Brokerages](/docs/connecting-banks/brokerages): link your investment accounts first - [How to Sync Holdings Data](/docs/bank-feeds/sync-holdings): current positions to pair with your trade history - [Managing Sync Jobs](/docs/bank-feeds/managing-sync-jobs): how backfills are chunked, paused, and retried - [Configuring Field Mappings](/docs/bank-feeds/field-mappings): full reference for the Mapping tab [Connect Your Brokerage](/docs/connecting-banks/brokerages) --- # How to Sync Transaction Data > Learn how to set up and configure transaction feeds to sync your bank transaction data to Notion, Google Sheets, or Airtable. > Source: https://banksync.io/docs/bank-feeds/sync-transactions Transaction feeds are the most common feed type in BankSync. Sync your checking, savings, and credit card transactions to keep track of spending, categorize expenses, and build financial dashboards. - **All Transactions** — Deposits, withdrawals, purchases, transfers - **Automatic Updates** — Sync runs automatically on schedule - **Rich Data** — Merchant, amount, date, category, and more - **Historical Data** — The first sync backfills available history automatically [![Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.poster.aab068ddd35cd6f7.png)](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) [Watch: Choosing a feed's data type in the source step: a credit-card account offering Transactions, Balances and Loans, and a brokerage offering Trades, Holdings and Orders, with each type mapping its own fields.](https://cdn.banksync.io/videos/feed-data-types.74f141571e05bb47.mp4) ## Available Transaction Fields Transaction feeds provide the following data fields for mapping: - **Date** — Transaction date - **Merchant** — Merchant or payee name - **Amount** — Transaction amount - **Category** — Auto-categorized type - **Account** — Source account name - **Status** — Pending or posted - **Type** — Debit, credit, transfer - **Description** — Bank-provided description ## Setting Up a Transaction Feed **Quick Setup Guide** 1. **Connect your bank** — Go to the Banks tab and connect the bank account containing your transactions. 2. **Create a new feed** — Click Create Feed and select 'Transactions' as the feed type in the Sources tab. 3. **Select accounts** — Choose which bank accounts to pull transactions from. You can include accounts from multiple banks in one feed. 4. **Pick an integration** — In the Destination tab, choose which integration receives the data (Google Sheets, Excel, Notion, Airtable, or a database). 5. **Configure mappings** — Map transaction fields to the columns in your sheet or table. 6. **Set schedule** — Choose a cadence: Hourly, Daily, or Weekly. Hourly and Daily are gated by plan; see the scheduling guide. You can also leave the feed on Manual and sync it yourself. ![The Mapping tab for a transactions feed writing to Notion, with the transaction fields Amount, Date, and Description each mapped to a Notion property and a green banner reading All 3 fields mapped successfully.](https://cdn.banksync.io/screenshots/feeds/field-mapping.2ab47ec069310b16.png "Map each transaction field to a column or property; the banner turns green when the mapping is complete.") ## First sync vs. ongoing syncs - **First sync (backfill)**: the first run pulls in available historical transactions. Long backfills are processed in 7-day chunks, so a multi-year backfill takes a while; see [Managing Sync Jobs](/docs/bank-feeds/managing-sync-jobs). How far back history goes varies by bank and provider. - **Ongoing syncs**: incremental runs (manual or scheduled) pick up only what's new since the last sync. Manual "Sync Now" uses the same read path as scheduled runs, so mixing them is safe. - **Deduplication**: BankSync keys each transaction on the bank provider's unique transaction ID, so overlapping runs and retries don’t create duplicate rows. ## Handling pending transactions Banks report transactions in two stages: a pending entry when the charge is authorized, then a posted entry when it settles (often with a corrected amount or description). BankSync has pending-transaction handling modes that control whether pending entries are synced or filtered out until they post. > **Why Australian (Fiskil) connections filter pending by default:** For Plaid and SnapTrade connections, transaction IDs are stable across the pending-to-posted transition, so pending transactions can be synced and deduplicated reliably. Australian CDR connections via Fiskil are different: a transaction's ID can change when it moves from pending to posted, which would create duplicates. Fiskil connections therefore default to filtering pending transactions, and a feed mixing Fiskil with other sources uses the stricter filtering default. Practical implications: - If a recent card purchase hasn't appeared in your sheet from an Australian bank, it's likely still pending; it will sync once it posts. - If you sync pending transactions, expect details like amount or merchant name to be finalized only when the transaction posts (restaurant tips are the classic example). ## Best Practices - **One Feed Per Target** — Avoid two feeds syncing the same account into the same sheet or table; each feed deduplicates independently, so overlapping feeds double up rows. - **Daily Sync Schedule** — Daily syncs balance freshness with API limits. Use Hourly (Professional plan and up) only if near-real-time data is critical. - **Consistent Categories** — Use bank-provided categories, or build your own categorization with enrichment rules for consistent expense tracking. - **Late-posting coverage** — Each run re-checks a window behind your last sync, so transactions that banks post a day or two late are still picked up; dedup makes the overlap safe. ## Common Use Cases - **Expense Tracking** — Monitor spending across categories with automatic updates - **Budget Dashboard** — Build budget vs. actual spending views that stay current - **Tax Preparation** — Track deductible expenses for easy tax filing ## Related guides - [Configuring Field Mappings](/docs/bank-feeds/field-mappings): the full Mapping tab reference for transaction fields - [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds): cadences, local-time scheduling, and plan gating - [Creating Enrichments](/docs/enrichments/creating-enrichments): rename, categorize, and tag transactions before they reach your sheet - [Troubleshooting Guide](/docs/bank-feeds/troubleshooting-guide): missing or duplicate transaction fixes [Configure Field Mappings](/docs/bank-feeds/field-mappings) --- # Configuring Field Mappings > Learn how to map bank data fields to the columns in your sheet, table, or database for precise data synchronization. > Source: https://banksync.io/docs/bank-feeds/field-mappings The **Mapping** tab is where you configure exactly what data gets synced and which columns it lands in. This guide walks through the interface and all available options. > **Prerequisites:** Before configuring field mappings, complete the Sources and Destination tabs in your feed configuration. Field mapping requires knowing which accounts you're syncing from and which integration you're syncing to. [![Configuring field mappings in the feed editor: the Mapping tab with bank fields auto-mapped to Notion properties, opening a row's destination picker to browse properties, adding a custom Category field, and the Advanced subtab's write-mode choice.](https://cdn.banksync.io/videos/field-mappings.poster.37d7e96a499943f0.png)](https://cdn.banksync.io/videos/field-mappings.f097b9e7a2e7026b.mp4) [Watch: Configuring field mappings in the feed editor: the Mapping tab with bank fields auto-mapped to Notion properties, opening a row's destination picker to browse properties, adding a custom Category field, and the Advanced subtab's write-mode choice.](https://cdn.banksync.io/videos/field-mappings.f097b9e7a2e7026b.mp4) ## Step 1: Choose What to Sync At the top of the **Mapping** tab, you'll see visual cards for each feed type. Each feed carries one data type; select the one you want: - **Transactions** — Individual transaction records with dates, amounts, descriptions - **Balances** — Account balance snapshots, tracked over time or kept current - **Trades** — Investment transactions (buys, sells, dividends) - **Holdings** — Current investment positions in your portfolio - **Loans** — Mortgages, credit lines, and other liabilities - **Orders** — Open and pending brokerage orders > **Account Compatibility:** Available feed types depend on your selected accounts. Investment accounts (Trades, Holdings, Orders) can't be mixed with depository accounts (Checking, Savings) in the same feed. ## Step 2: Balance Sync Mode When syncing balances (or other point-in-time data like holdings and loans), choose how updates are written: - **Append** — Adds a new row each sync with a timestamp. Use this to track changes over time and build historical data. - **Overwrite** — Updates the same rows in place, keeping only the most recent value for each account. Best for dashboards showing current state. ## Step 3: Map Your Fields The field mapping section shows two areas: ### Mapped Fields (Top) Shows fields currently included in your feed. Each row displays: - **Source Field** — The bank data field (e.g., Date, Description, Amount) - **Target Column** — The column or property it maps to in your sheet, table, or database - **Drag Handle** — Reorder fields by dragging - **Remove Button** — Click X to remove a field from the mapping ### Available Fields (Bottom) Shows fields not yet added to your mapping. Click the plus icon or drag a field card to add it. ### Using Auto-Fill Click the Auto fill button (with sparkle icon) to automatically match source fields to the columns in your sheet or table: - For Google Sheets: Auto-assigns sequential column letters (A, B, C...) to each field - For Notion/Airtable: Matches fields by name similarity (e.g., "Date" → "Date" column) > **Auto-Fill Behavior:** Auto-fill only fills fields that aren't mapped to a column yet. If you've already mapped some fields, it will only fill the remaining unmapped ones. ![The Mapping tab for a transactions feed writing to Notion: a green banner reads All 3 fields mapped successfully above a table mapping the transaction fields Amount, Date, and Description to the Notion properties Amount, Date, and Description, with Clear fields and Auto-fill controls and a note that all available fields are added.](https://cdn.banksync.io/screenshots/feeds/field-mapping.2ab47ec069310b16.png "The Mapping tab with every field mapped: the banner flips green when nothing needs attention.") ## Mapping by Integration How you target columns depends on which integration the feed writes to. ### Google Sheets You map each field to a column reference (A, B, C, etc.). The order of your field mappings determines which data goes in which column. - **Date → A** — Transaction date - **Description → B** — Merchant name - **Debit → C** — Money out - **Credit → D** — Money in A nuance worth knowing: column references are positional. If you insert or delete columns in your sheet later, the mapped letters keep pointing at the same positions, so revisit the **Mapping** tab after restructuring a sheet. ### Notion & Airtable You map to specific database properties. BankSync fetches your database schema and shows a dropdown of available properties: - BankSync validates field type compatibility (date → date, number → number) - Warnings appear if types don't match - Used properties show as greyed out to prevent duplicate mappings Because properties are referenced by name rather than position, renaming or deleting a property in Notion or Airtable breaks the mapping until you re-select it. ## Transaction Fields Reference - **Date** — Transaction date (Date type) - **Description** — Transaction description (Text) - **Credit Amount** — Amount credited (Number) - **Debit Amount** — Amount debited (Number) - **Category** — Transaction category (Text) - **Type** — Transaction type (Text) - **Bank** — Bank name (Text) - **Account** — Account name (Text) - **ID** — Unique identifier (Text) ## Tips for Effective Field Mapping 1. **Start with essential fields** — For transactions, Date, Description, and Amount fields are usually most important. Add more fields as needed. 2. **Use Bank and Account for filtering** — If syncing multiple accounts, include these fields to easily filter and analyze data by source. 3. **Match field types when possible** — Mapping number fields to number columns enables sorting and calculations in your sheet or database. 4. **Save incomplete mappings** — Not ready to finish? Your configuration auto-saves, and you can return to complete it later. > **Next Steps:** 'After configuring your field mappings, proceed to the Schedule tab to set when your feed runs, or click Run Now to test your configuration immediately.' ## Related guides - [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds): the next step after mapping - [Creating Your First Feed](/docs/bank-feeds/creating-first-feed): the end-to-end setup walkthrough this tab belongs to - [Creating Enrichments](/docs/enrichments/creating-enrichments): transform and categorize data before it reaches your columns - [Troubleshooting Guide](/docs/bank-feeds/troubleshooting-guide): fixes for property mismatches and broken mappings [View Scheduling Guide](/docs/bank-feeds/scheduling-feeds) --- # Setting Up Scheduled Feeds > Automate your feeds with hourly, daily, or weekly schedules, in your own time zone, with email notifications when a run fails. > Source: https://banksync.io/docs/bank-feeds/scheduling-feeds BankSync can run your feeds automatically on a schedule, so your spreadsheet, database, or Notion workspace stays current without you having to click anything. This guide covers the available cadences, how plan limits affect them, and how to pick settings that match how you use your data. [![Setting a feed's sync schedule: choosing the cadence (hourly, daily, weekly or manual), the run time and day, the schedule forecast, and kicking off the first sync.](https://cdn.banksync.io/videos/schedule-a-feed.poster.c4afe0c63cef7d33.png)](https://cdn.banksync.io/videos/schedule-a-feed.048087b62e18cf42.mp4) [Watch: Setting a feed's sync schedule: choosing the cadence (hourly, daily, weekly or manual), the run time and day, the schedule forecast, and kicking off the first sync.](https://cdn.banksync.io/videos/schedule-a-feed.048087b62e18cf42.mp4) ## Schedule Options Open a feed from the Feeds tab and go to the **Schedule** tab. You choose one of four modes: - **Hourly** — Every hour, around the clock. For near-real-time dashboards. - **Daily** — Once a day, at a time you choose - **Weekly** — Once a week, on a day you choose - **Manual** — Only when you trigger it with Sync Now ![The feed editor Schedule tab with four frequency cards (Hourly with a PRO badge, Daily selected, Weekly, and Manual), an hour picker labeled Run at with the user's time zone shown as UTC+10 Australia/Sydney and 9AM selected, a note that schedules run at the top of the hour, and a Schedule Forecast panel listing the next three runs and the last three actual runs.](https://cdn.banksync.io/screenshots/feeds/schedule.d06df9cac0def0e3.png "The Schedule tab: pick a cadence, pick an hour in your own time zone, and check the run forecast.") Selecting **Manual** simply turns scheduling off: the feed only runs when you click Sync Now, and your cadence settings are kept for when you re-enable a schedule. ### Cadences by plan Which cadences you can choose depends on your workspace plan. Gated cadences appear locked in the Schedule tab (Hourly carries a PRO badge): | Plan | Scheduled cadences | | ------------ | --------------------- | | Free | Weekly | | Starter | Weekly | | Standard | Daily, Weekly | | Professional | Hourly, Daily, Weekly | | Business | Hourly, Daily, Weekly | | Enterprise | Hourly, Daily, Weekly | > **Need a faster cadence?:** If Hourly or Daily is locked in the Schedule tab, it's gated by your plan. See Managing Your Plan for upgrade options. Manual syncs (Sync Now) work on every plan regardless of schedule settings. ### Times are in your time zone The **Run at** hour picker works in your local time zone, which is shown right next to it (for example, "UTC+10 · Australia/Sydney"). Pick the hour you want; BankSync converts it to UTC behind the scenes and keeps the run time stable. - Schedules run at the top of the hour. There is no minute-level precision. - Hourly feeds ignore the time-of-day setting entirely; they simply run about once an hour. - Weekly feeds add a day-of-week picker alongside the hour picker. ### The Schedule Forecast Below the pickers, the **Schedule Forecast** panel shows the next three planned runs and the last three actual runs, so you can confirm the schedule does what you expect before leaving the tab. ### Email notifications The Schedule tab also has per-feed notification toggles: - **Sync failed**: send an email when this sync fails to complete (on by default, and worth keeping on for any scheduled feed). - **Sync succeeded**: send an email when this sync completes successfully (off by default; useful while testing a new feed). ## Setting Up a Scheduled Feed 1. **Edit Your Feed** — From your Feeds tab, find the feed you want to schedule and click to open it. 2. **Open the Schedule tab** — Click the "Schedule" tab in the feed editor. 3. **Pick a cadence** — Choose Hourly, Daily, or Weekly. Choosing Manual disables automatic runs. 4. **Pick a time** — For Daily and Weekly, choose the hour (in your local time zone). For Weekly, also pick the day of the week. 5. **Check the forecast** — Confirm the next runs in the Schedule Forecast panel look right. 6. **Set notifications** — Decide whether you want an email on failure (recommended) or on success. > **Auto-Save:** Your schedule configuration is automatically saved as you make changes. You'll see a status indicator showing when changes are saved. ## How scheduled runs behave - The first run after you enable a schedule behaves like any other sync: it picks up from where the feed's last sync left off (or performs the initial backfill if the feed has never synced). - Scheduled syncs and manual **Sync Now** runs use the same read path and the same deduplication, so mixing them never creates duplicates. - Each run appears in the feed's History list, exactly like a manual run. See [Managing Sync Jobs](/docs/bank-feeds/managing-sync-jobs) for monitoring details. - Feeds created before cadence options changed may still show a legacy Monthly schedule; they keep running monthly until you pick a new cadence. ## Recommended Configurations - **Personal Finances** — Daily sync in the morning, so overnight transactions are waiting for you - **Business Accounts** — Daily sync around midday, after most banks have posted morning settlements - **Live Dashboards** — Hourly sync (Professional and above) for boards and screens that stay open ## Important Notes > **Keep Connections Active:** 'Scheduled feeds require your bank connections to remain active. If a connection expires or needs re-authentication, scheduled syncs will fail until you reconnect the bank. See Reconnecting a Bank for how to fix this.' - You can still run manual syncs at any time, even with scheduling enabled - Switching to Manual pauses automatic runs without losing your cadence configuration - Balance, holdings, and loan feeds capture point-in-time values, so the schedule cadence directly determines how granular your history is (a weekly balance feed gives you one data point per week) ## Related guides - [Managing Sync Jobs](/docs/bank-feeds/managing-sync-jobs): monitor, pause, and retry the jobs your schedule creates - [Managing Your Feeds](/docs/bank-feeds/managing-feeds): everything else about editing and running feeds - [Reconnecting a Bank](/docs/connecting-banks/reconnecting-a-bank): fix the most common cause of failed scheduled syncs - [Managing Your Plan](/docs/account-billing/managing-your-plan): unlock Daily and Hourly cadences [View Managing Feeds Guide](/docs/bank-feeds/managing-feeds) --- # Managing Sync Jobs > Learn how to manage, monitor, and troubleshoot your sync jobs for smooth data processing. > Source: https://banksync.io/docs/bank-feeds/managing-sync-jobs Every time a feed runs (manually with Sync Now, or automatically on a schedule) BankSync creates a sync job. The job is the unit of work you can watch, pause, resume, and retry. This guide explains how jobs work and how to manage them. [![Backfilling a feed and reading its run history: the Sync panel's up-to-date state, opening Backfill to re-import a chosen date range with the duplicate-rows warning, and the recent-runs log with processed and written counts.](https://cdn.banksync.io/videos/feed-backfill-history.poster.1473c004721fffb3.png)](https://cdn.banksync.io/videos/feed-backfill-history.958d732904a322e9.mp4) [Watch: Backfilling a feed and reading its run history: the Sync panel's up-to-date state, opening Backfill to re-import a chosen date range with the duplicate-rows warning, and the recent-runs log with processed and written counts.](https://cdn.banksync.io/videos/feed-backfill-history.958d732904a322e9.mp4) ## Understanding Sync Jobs Each job moves data from your bank accounts to the integration configured in the feed's **Destination** tab: **Job Processing Steps** 1. **Divides into chunks** — For backfills, your date range is split into manageable 7-day periods. A short incremental sync may be a single chunk. 2. **Processes sequentially** — Each chunk is processed one at a time. 3. **Fetches records** — Transactions (or balances, holdings, trades, or loans, depending on the feed's data type) are retrieved from your bank for each period. 4. **Deduplicates** — Records that were already written by a previous sync are skipped, so overlapping date ranges and re-runs are safe. 5. **Maps the data** — Data is transformed according to your field mappings. 6. **Writes to your integration** — Processed rows are sent to your sheet, table, or database. 7. **Provides updates** — Real-time progress is shown throughout. ### First sync vs. subsequent syncs - **First sync**: there's no sync history yet, so the job performs the initial backfill of all available history. Long historical backfills are chunked into 7-day periods, which is why a multi-year backfill shows many chunks and takes longer. - **Subsequent incremental syncs**: the job picks up from where the last successful sync left off, so it's usually a single fast chunk. - **Manual vs. scheduled**: a manual "Sync Now" uses exactly the same read path and deduplication as a scheduled run. Running one manually never causes duplicates alongside the schedule. ### How deduplication works BankSync keys each record on the unique identifier issued by the bank provider and skips records it has already written for that account. This is why you can safely overlap date ranges, retry failed jobs, or run a manual sync minutes before a scheduled one. The exceptions: two different feeds writing the same account to the same sheet are deduplicated independently (each feed keeps its own history), and rows you edit or delete in your sheet or table are not re-detected. See the [Troubleshooting Guide](/docs/bank-feeds/troubleshooting-guide) if you're seeing duplicates. ## Viewing Job Status **Access Job History** 1. **Open your feed** — From the Feeds tab, click on the feed you want to check. 2. **Click "History"** — View all past and current sync jobs for this feed. 3. **Click a job for details** — See progress percentage, the date range covered, record counts, and any errors. ![The Feed History dialog for a feed named Chase to Sheets: a left sidebar lists three runs (a completed run with 42 transactions written, a failed run, and a running one), and the details panel for the selected completed run shows a Scheduled badge, stat cards for 44 transactions processed and 42 transactions written, and Run Details with the start time, an 11 second duration, and the completion time.](https://cdn.banksync.io/screenshots/feeds/sync-history.c2758d2ddce7f927.png "The feed's History dialog: every run with its status, counts, and timing.") ### Job Status Indicators - **Created** — Job created but not yet started - **In Progress** — Job is actively processing chunks - **Completed** — All chunks processed successfully - **Paused** — Job paused by user - **Failed** — Job encountered errors > **A completed job with 0 rows isn't necessarily a problem:** If no new transactions posted since the last sync, the job completes successfully with nothing to write. Check the job's date range before assuming data is missing. ## Job Control Actions ### Pausing a Job 1. **Open the job details** — Click on the running job in the history list. 2. **Click the "Pause" button** — The pause option appears for in-progress jobs. 3. **Job stops after current chunk** — The job finishes its current chunk before pausing, so no chunk is left half-written. ### Resuming a Job 1. **Open the paused job** — Find the paused job in the history list. 2. **Click "Resume"** — The resume button appears for paused jobs. 3. **Job continues from where it stopped** — Processing resumes from the next unprocessed chunk; completed chunks are never redone. ### Retrying a Failed Job 1. **Review error messages** — Open the failed job to understand what went wrong. Error details include remediation suggestions where possible. 2. **Resolve the issue** — Fix the problem first (for example, reconnect the bank in the Banks tab if the connection expired, or re-authorize the integration in the Integrations tab). 3. **Click "Retry"** — The job restarts failed chunks while preserving successful ones, and deduplication prevents any rows written before the failure from being written twice. ## Troubleshooting Tips - **Bank Connection Issues** — If a job fails due to bank authentication, reconnect your bank in the Banks tab, then retry the job. - **Rate Limits** — Some banks and integrations limit API calls. Wait a few minutes before retrying if you hit a rate limit. - **Large Date Ranges** — Processing years of transactions takes time because each 7-day chunk is fetched and written separately. Consider backfilling in stages (for example, one year at a time). - **Integration Connectivity** — Ensure the integration this feed writes to (Google Sheets, Excel, Notion, Airtable, or a database) is healthy in the Integrations tab. > **Quick Fix for Most Issues:** 'Most sync job failures are due to expired bank connections. Check the Banks tab first and reconnect any banks showing a warning or error status.' ## Related guides - [Troubleshooting Guide](/docs/bank-feeds/troubleshooting-guide): diagnose connection, sync, and data issues in depth - [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds): the schedules that create jobs automatically - [Reconnecting a Bank](/docs/connecting-banks/reconnecting-a-bank): fix the most common cause of failed jobs - [Managing Integrations](/docs/integrations/managing-integrations): re-authorize the integrations your feeds write to [View Troubleshooting Guide](/docs/bank-feeds/troubleshooting-guide) --- # Managing Your Feeds > Learn how to create, configure, and manage your feeds effectively. > Source: https://banksync.io/docs/bank-feeds/managing-feeds Feeds are the core of BankSync: each feed defines how one type of data flows from your bank accounts into one of your integrations (Google Sheets, Excel, Notion, Airtable, or a database). This guide covers the day-to-day work of editing, running, and monitoring feeds after you've created your first one. [![Managing feeds in BankSync: reading feed health from the grid, opening card actions, resuming a paused feed, jumping into the editor, and returning to an all-healthy feed list.](https://cdn.banksync.io/videos/manage-feeds.poster.85d540ce2519b910.png)](https://cdn.banksync.io/videos/manage-feeds.0c4087dbd648bd84.mp4) [Watch: Managing feeds in BankSync: reading feed health from the grid, opening card actions, resuming a paused feed, jumping into the editor, and returning to an all-healthy feed list.](https://cdn.banksync.io/videos/manage-feeds.0c4087dbd648bd84.mp4) Every feed appears as a card on the **Feeds** tab, so you can read its health without opening it: ![A feed card named Operating Account to Notion showing 2 accounts flowing to Notion, a Transactions data type chip, a Daily schedule badge, and a green check indicating the last sync succeeded.](https://cdn.banksync.io/screenshots/feeds/feed-card.e7d2743267daae2d.png "A feed card on the Feeds tab: source accounts, integration, data type, cadence, and last-run status at a glance.") ## Anatomy of a feed A feed carries exactly one data type: Transactions, Balances, Holdings, Trades, Orders, or Loans. If you want both transactions and balances from the same accounts, create two feeds. Each feed is configured across four steps in the feed editor, with an **Overview** tab summarizing the whole setup: - **1. Sources** — Select bank accounts - **2. Destination** — Choose which integration receives the data - **3. Mapping** — Map data fields to columns - **4. Schedule** — Set automation The feed editor's **At a glance** panel shows whether each step is complete. A feed only runs once every row shows a real value. ![The feed editor's At a glance summary panel showing four configured rows: From (the selected bank), To (the receiving integration), Mapping (number of mapped fields), and Schedule (the sync cadence), each with an edit link](https://cdn.banksync.io/screenshots/feeds/sync-at-a-glance.9ab0f122dcacd92a.png "The At a glance panel confirms all four steps are configured") ### Sources tab 1. **Choose accounts from multiple banks** — Select any combination of accounts from your connected banks. Investment accounts can't be mixed with checking/savings accounts in the same feed. 2. **View account balances and types** — See current balances and account types (Checking, Savings, Credit Card, etc.). 3. **Save and continue later** — Your progress auto-saves; return to finish if banks aren't connected yet. ### Destination tab 1. **Select an integration** — In the Destination tab, choose which of your connected integrations receives the data. 2. **Specify the exact target** — Select the specific spreadsheet and sheet, database, base and table, or workbook within that integration. 3. **For Notion: search databases by name** — Use the search field to find databases quickly. ### Mapping tab - Select the data type: Transactions, Balances, Trades, Holdings, or Loans - Use "Auto fill" for automatic field suggestions - Drag and drop to reorder fields - Add or remove fields as needed - For balance-style feeds, choose **Append** (a new timestamped row each sync) or **Overwrite** (update the same rows in place) See [Configuring Field Mappings](/docs/bank-feeds/field-mappings) for the full walkthrough. ### Schedule tab - Enable or disable scheduled syncing - Choose a cadence: Hourly, Daily, or Weekly, or Manual (Hourly and Daily are gated by plan; see [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds)) - Pick the run hour (in your local time zone, shown next to the picker) ![The Schedule tab with frequency cards for Hourly (marked PRO), Daily (selected), Weekly, and Manual, an hour picker labeled Run at showing the user's time zone, and a Schedule Forecast listing the next three and last three runs.](https://cdn.banksync.io/screenshots/feeds/schedule.d06df9cac0def0e3.png "The Schedule tab: cadence cards, a local-time hour picker, and the run forecast.") ## How many feeds can I have? Feed limits depend on your workspace plan: Free allows 1 feed, Starter 2, Standard 5, and Professional, Business, and Enterprise have no feed limit. If you've hit your cap, the create button will tell you; see [Managing Your Plan](/docs/account-billing/managing-your-plan). ## Running Feeds - **Incremental Sync** — Syncs only new records since the last sync. Fast, avoids duplicates, and maintains cursor state. This is what scheduled runs do. - **Start from the beginning** — An optional Sync Now checkbox that re-fetches all available data from scratch. Useful if you suspect a gap, but it can duplicate rows that were already written. A few behaviors worth knowing: - **First run vs. later runs**: the first run of a new feed backfills the history available from your bank. Every run after that is incremental. - **Manual and scheduled runs mix safely**: "Sync Now" uses the same read path and deduplication as scheduled syncs, so triggering a manual run never creates duplicates. - **Overlap is safe**: deduplication is keyed on the bank's unique record IDs, so re-running an already-synced date range writes nothing new. > **Recommendation:** Use the default incremental Sync Now for regular updates: it's fast and avoids duplicates. Reach for Start from the beginning only when you need a full re-fetch. ## Monitoring Sync Jobs Click "History" on any feed to view sync history and job details: ### Job Status - **Running** — Job is processing - **Completed** — Finished successfully - **Failed** — Encountered errors - **Paused** — Paused by user ### Job Metrics - Records processed - Records written to your sheet, table, or database - Execution duration - Error details (if any), with remediation suggestions For pausing, resuming, and retrying jobs, see [Managing Sync Jobs](/docs/bank-feeds/managing-sync-jobs). ## Common pitfalls - **Editing the mapped columns**: if you rename or delete columns in your sheet or database properties in Notion/Airtable, the feed's mapping can break. Update the **Mapping** tab after restructuring your sheet or table. - **Two feeds, one account, one sheet**: each feed deduplicates independently, so two feeds syncing the same account into the same sheet will double up rows. Keep one feed per account per target. - **Expired connections**: a feed silently depends on its bank connection and its integration staying authorized. If runs start failing, check the Banks tab and the Integrations tab first. > **Pro Tips:** '• Start with a single account and integration to test your setup\n• Use descriptive feed names for easy identification\n• Run one manual sync and check the columns line up before scheduling\n• Monitor initial syncs to ensure data appears correctly\n• Set up scheduled syncs after confirming manual syncs work' ## Related guides - [Managing Sync Jobs](/docs/bank-feeds/managing-sync-jobs): pause, resume, and retry the jobs your feeds create - [Configuring Field Mappings](/docs/bank-feeds/field-mappings): the full Mapping tab reference - [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds): cadences, UTC timing, and plan gating - [Troubleshooting Guide](/docs/bank-feeds/troubleshooting-guide): when a feed stops working [View Sync Jobs Guide](/docs/bank-feeds/managing-sync-jobs) --- # Troubleshooting Guide > Solutions for common issues with bank connections, feed syncs, integrations, and data problems. > Source: https://banksync.io/docs/bank-feeds/troubleshooting-guide This guide helps you diagnose and resolve common issues you might encounter when using BankSync. Find solutions for connection problems, sync failures, and data issues. - **Connection Issues** — Problems connecting to banks or integrations - **Sync Failures** — Feeds not running or completing properly - **Integration Errors** — Issues writing to Notion, Sheets, or Airtable - **Data Problems** — Missing, duplicate, or incorrect data [![Reconnecting an expired bank in the BankSync app: the Banks page with a Chase card showing Reconnection needed, clicking Reconnect, reauthorizing through Plaid's secure window, and the card returning to healthy and syncing.](https://cdn.banksync.io/videos/reconnect-a-bank.poster.204bccccc185660a.png)](https://cdn.banksync.io/videos/reconnect-a-bank.fa0e69267315e642.mp4) [Watch: Reconnecting an expired bank in the BankSync app: the Banks page with a Chase card showing Reconnection needed, clicking Reconnect, reauthorizing through Plaid's secure window, and the card returning to healthy and syncing.](https://cdn.banksync.io/videos/reconnect-a-bank.fa0e69267315e642.mp4) ## Bank Connection Issues **Connection Troubleshooting Steps** 1. **Check your bank's status** — Visit your bank's website or app to ensure online banking is working. Some banks have maintenance windows. 2. **Verify your credentials** — Ensure you're using the correct username and password. Try logging into your bank directly first. 3. **Complete any MFA challenges** — Look for text messages, emails, or app notifications for verification codes. 4. **Reconnect if needed** — Go to the Banks tab, find the connection, and click Reconnect to re-authenticate. > **Security Lockouts:** Multiple failed connection attempts may trigger your bank's security measures. Wait 15-30 minutes before trying again, or contact your bank to unlock your account. ### Common Bank Connection Errors - **Invalid Credentials** — Double-check username/password. Some banks use different credentials for third-party access. - **Session Timeout** — The connection took too long. Try again when you have a stable internet connection. - **MFA Required** — Complete the multi-factor authentication challenge sent to your phone or email. - **Bank Maintenance** — Your bank may be performing maintenance. Try again in a few hours. For region-specific connection guidance, see the guides for [US banks](/docs/connecting-banks/us-banks), [Canadian banks](/docs/connecting-banks/canadian-banks), and [Australian banks](/docs/connecting-banks/australian-banks). ## Feed Sync Issues **Feed Troubleshooting Steps** 1. **Check feed status** — Go to your Feeds tab and look for error indicators. Red status means a failure occurred. 2. **Review the sync job** — Click on the feed, then "History", to see the latest sync job details and any error messages with remediation suggestions. 3. **Verify bank connection** — Ensure the underlying bank connection is healthy in the Banks tab. Expired bank connections are the most common cause of failed syncs. 4. **Check the integration** — Verify the integration the feed writes to (Google Sheets, Excel, Notion, Airtable, or a database) is still authorized in the Integrations tab. 5. **Retry the sync** — Use the Run Now button to manually trigger a new sync attempt. Retried jobs restart failed chunks only, and deduplication prevents already-written rows from being duplicated. > **Pro Tip:** 'If a feed consistently fails, try pausing it, waiting a few minutes, then resuming. This can clear transient errors.' ![The Feed History dialog showing a completed run with transaction counts, a failed run whose error reads that the bank connection needs to be re-authorized, and an in-progress run, with full run details for the selected job.](https://cdn.banksync.io/screenshots/feeds/sync-history.c2758d2ddce7f927.png "The feed History dialog is the first place to look: every run, its counts, and the exact error.") ### Scheduled syncs not running If a scheduled feed doesn't seem to fire when you expect: - **Check the time zone**: schedule times are interpreted in UTC, not your local time. A "06:00" schedule runs at 06:00 UTC. - **Check the cadence is allowed on your plan**: Free and Starter plans support Weekly schedules, Standard adds Daily, and Hourly requires Professional or above. See [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds). - **Check the toggle**: the "Automatically sync periodically" toggle in the Schedule tab must be on. ## Integration Issues ### Notion - **Permission Denied** — Re-authorize Notion and ensure BankSync has access to the target database. - **Database Not Found** — The database may have been deleted or moved. Select a new database in your feed's Destination tab. - **Property Mismatch** — Database properties changed. Update your field mappings to match the current schema. - **Rate Limited** — Notion API limits reached. The sync will automatically retry later. ### Google Sheets - **Access Revoked** — Re-authorize Google Sheets in the Integrations tab to restore access. - **Sheet Not Found** — The spreadsheet may have been deleted or unshared. Select a new sheet in your feed's Destination tab. - **Row Limit Reached** — Google Sheets has a 10 million cell limit. Archive old data or use a new sheet. - **Quota Exceeded** — Google API quota reached. Syncs will resume automatically. ### Airtable - **Token Expired** — Re-authorize Airtable in the Integrations tab. - **Base Not Found** — The base may have been deleted. Select a different base for your feed. - **Field Type Mismatch** — Field types changed in Airtable. Update your mappings to match. - **Record Limit** — Free Airtable plans have record limits. Upgrade or archive old data. ## Data Issues ### Missing Data **Resolving Missing Data** 1. **Check the sync window** — Run Sync Now first: it picks up anything new since the last run. If data is still missing, use "Start from the beginning" in the Sync Now dialog to re-fetch all available history (note: this can create duplicate rows for data that was already written). 2. **Verify bank data** — Check if the transactions appear in your bank's online portal. A bank can take a day or more to post new transactions. 3. **Consider pending transactions** — If the feed filters pending transactions, recent purchases appear only once they post. Australian (CDR) bank connections filter pending transactions by default because their IDs can change when the transaction posts. 4. **Review filters and mappings** — Check whether enrichment rules or feed settings exclude certain transactions, and confirm the relevant fields are mapped to columns. ### Duplicate Data > **How Deduplication Works:** BankSync keys every record on the unique ID issued by the bank provider and remembers what it has already written for each account, so re-runs, retries, and overlapping date ranges don't duplicate rows. Duplicates usually mean two feeds are writing the same account to the same place (each feed deduplicates independently), or the bank changed its transaction IDs. **Fixing Duplicates** 1. **Check for duplicate feeds** — Ensure only one feed syncs a given bank account into each sheet, table, or database. 2. **Clean up your sheet or table** — Remove the duplicate rows manually or with filters. 3. **Reset the feed** — If duplicates persist, you may need to delete the feed and create a new one. ## Getting More Help > **Contact Support:** If you've tried these troubleshooting steps and still need help, contact our support team with details about your issue, including any error messages and steps to reproduce the problem. [Contact Support](mailto:support@banksync.com) ## Related guides - [Managing Sync Jobs](/docs/bank-feeds/managing-sync-jobs): job statuses, chunking, pause/resume, and retries in depth - [Reconnecting a Bank](/docs/connecting-banks/reconnecting-a-bank): the fix for the most common sync failure - [Managing Integrations](/docs/integrations/managing-integrations): re-authorize Google Sheets, Excel, Notion, Airtable, and databases - [Setting Up Scheduled Feeds](/docs/bank-feeds/scheduling-feeds): UTC timing and plan-gated cadences --- # Install the CLI > Install the BankSync CLI on macOS, Linux, and Windows with the one-line installer. It is a self-contained binary that needs no Node, verify it, and keep it up to date. > Source: https://banksync.io/docs/cli/installation The BankSync CLI (`banksync`) brings your workspace to the terminal: connect banks, pull transactions, manage feeds, trigger syncs, and drive automation. It is a single command that works the same on macOS, Linux, and Windows, and it is built to be scriptable and agent-friendly. `banksync` is a single, self-contained native binary. It has **no runtime dependency** (no Node, nothing to install or manage) to either install or run. The one-line installer detects your OS and CPU, downloads the right build, verifies its checksum, and puts `banksync` on your PATH. [![BankSync CLI in action](https://cdn.banksync.io/videos/cli-quickstart.poster.5f7c1b212f341fe5.png)](https://cdn.banksync.io/videos/cli-quickstart.beab24a10f6ffdb2.mp4) [Watch: BankSync CLI in action](https://cdn.banksync.io/videos/cli-quickstart.beab24a10f6ffdb2.mp4) > **No runtime required:** The binary bundles everything it needs, so you do not need Node (or any other runtime) installed. > The CLI always talks to production, so there is nothing to configure after install. - **One command** — A single installer for macOS, Linux, and Windows. Nothing to configure. - **Self-contained** — A single executable with its runtime baked in: no Node, no dependencies. - **Self-updating** — Run banksync update any time; it fetches, verifies, and swaps in the latest build. ## macOS and Linux Run the one-line installer. It detects your OS and CPU architecture, downloads the matching build, verifies its SHA-256, and puts `banksync` on your PATH. ```bash curl -fsSL https://banksync.io/install.sh | sh ``` If you prefer to inspect the script before running it, download it first, read it, then run it: ```bash curl -fsSL https://banksync.io/install.sh -o install-banksync.sh less install-banksync.sh sh install-banksync.sh ``` The installer puts the binary in `/usr/local/bin` if it is writable, otherwise `~/.local/bin`. If that directory is not already on your PATH, the installer tells you the one line to add. ## Windows Run the one-line installer in PowerShell. It downloads the right build, verifies its checksum, and adds `banksync` to your user PATH. ```powershell irm https://banksync.io/install.ps1 | iex ``` Prefer to inspect it first? Download, read, then run: ```powershell irm https://banksync.io/install.ps1 -OutFile install-banksync.ps1 notepad install-banksync.ps1 ./install-banksync.ps1 ``` > **Homebrew is coming:** A Homebrew tap (brew install banksync) is planned for a future release. Until then, use the > install script on macOS. ## Verify the install Confirm the command is on your PATH and prints a version: ```bash banksync --version ``` ```text @banksync/cli/0.1.0 darwin-arm64 ``` Then see the full command tree and grouped help: ```bash banksync --help ``` ## Keep it up to date The CLI updates itself. Run: ```bash banksync update ``` It checks for a newer release, downloads the build for your platform, verifies its SHA-256 checksum, and replaces the binary in place. To see whether a newer version exists without installing it, use `banksync update --check`. Re-running the installer is equivalent and also works: ```bash # macOS / Linux curl -fsSL https://banksync.io/install.sh | sh ``` ```powershell # Windows irm https://banksync.io/install.ps1 | iex ``` To check what you are running at any time, use `banksync --version`. ## Next steps - [Quickstart](/docs/cli/cli-quickstart): log in and pull your first transactions in about a minute. - [Authentication](/docs/cli/cli-authentication): API keys, profiles, and credential storage. - [For agents](/docs/cli/for-agents): give an AI agent the CLI and an API key. --- # Quickstart > Install the BankSync CLI, log in with an API key, list your banks, and pull transactions in under a minute. > Source: https://banksync.io/docs/cli/cli-quickstart From zero to transactions in your terminal in about a minute. This assumes you have already [installed the CLI](/docs/cli/installation). [![BankSync CLI quickstart](https://cdn.banksync.io/videos/cli-quickstart.poster.5f7c1b212f341fe5.png)](https://cdn.banksync.io/videos/cli-quickstart.beab24a10f6ffdb2.mp4) [Watch: BankSync CLI quickstart](https://cdn.banksync.io/videos/cli-quickstart.beab24a10f6ffdb2.mp4) **Get running** 1. **Create an API key** — In the BankSync app, open Settings > Developers and create a key. Copy the bsk\_ secret when it is shown, because it appears only once. See the API keys guide for scopes and expiration. 2. **Log in** — Store the key for the CLI. It is validated against your workspace before it is saved. 3. **List your banks** — Confirm the key works and see your connected institutions. 4. **Pull transactions** — List transactions for a bank, resolving the bank by name or id. 5. **Pipe to a tool** — Because output is JSON when piped, the CLI drops straight into jq, scripts, and agents. ## 1. Log in ```bash banksync login --api-key bsk_your_api_key_here ``` The CLI calls `whoami` to validate the key, then saves it to an encrypted file for future commands. You will not need to pass `--api-key` again on this machine. ```text Logged in to Acme Inc (profile: default). ``` ## 2. List your banks ```bash banksync banks list ``` On a terminal you get an aligned table with a status column: ```text ID NAME SOURCE TYPE STATUS bnk_a1b2 Chase plaid personal ● active bnk_c3d4 Amex plaid personal ● active bnk_e5f6 CommBank fiskil personal ◐ syncing 3 banks · workspace acme ``` ## 3. Pull transactions Reference a bank by its id, or by name (partial names resolve): ```bash banksync transactions list --bank amex ``` `transactions list` has a short alias, `tx`, and accepts a date range: ```bash banksync tx list --bank amex --from 2026-01-01 --to 2026-03-31 ``` ## 4. Pipe to jq When stdout is not a terminal, the CLI emits its stable JSON envelope automatically, so pipelines just work with no flag: ```bash banksync tx list --bank amex | jq '.data[] | {date, description, amount}' ``` You can also ask for JSON explicitly with `--json` (or `-o json`): ```bash banksync banks list --json | jq '.data | length' ``` > **Everything is discoverable from the terminal:** Run banksync --help for the full command tree, banksync \ --help for a command's flags and examples, and banksync commands --json for a machine-readable catalog. You never have to leave the shell to find your way around. ## Where to go next - **Authentication** — API keys, the BANKSYNC\_API\_KEY env var, profiles, and where credentials are stored.' ' Read more - **Output formats** — Tables for humans, JSON and NDJSON for machines, plus --fields and --sort.' ' Read more - **Syncing and jobs** — Trigger syncs, watch them to completion, and inspect job history.' ' Read more - **Connecting banks** — Link a new bank through the web app and wait for it to appear.' ' Read more --- # Authentication > Sign in to the BankSync CLI with a browser OAuth flow or an API key, use the BANKSYNC_API_KEY env var, manage profiles, and understand where credentials are stored. > Source: https://banksync.io/docs/cli/cli-authentication The CLI supports two ways to authenticate. Run `banksync login` with no flags to sign in through your browser using OAuth 2.1 (Authorization Code with PKCE over a loopback redirect); there is no key to copy. For CI, containers, scripts, and AI agents, use an API key instead by passing `--api-key` or setting `BANKSYNC_API_KEY`. An API key is the same credential the REST API and MCP server use, so a key that works for one works for all three. [![Authenticate the BankSync CLI](https://cdn.banksync.io/videos/cli-quickstart.poster.5f7c1b212f341fe5.png)](https://cdn.banksync.io/videos/cli-quickstart.beab24a10f6ffdb2.mp4) [Watch: Authenticate the BankSync CLI](https://cdn.banksync.io/videos/cli-quickstart.beab24a10f6ffdb2.mp4) > **API keys are created in the dashboard:** The CLI never creates or revokes keys. Create one in the app under Settings > Developers, choosing the least-privilege scopes the command needs. See the API keys guide for scopes, expiration, and rotation. Every key starts with the bsk\_ prefix. ## Log in Run `login` with no flags to sign in through your browser. The CLI starts a temporary loopback listener, opens the BankSync authorization page, and finishes once you approve: ```bash banksync login ``` ```text Opening your browser to authorize BankSync CLI. If it does not open, visit this URL: https://auth.banksync.io/authorize?... Waiting for approval... Logged in to Acme Inc (profile: default). ``` On a headless or SSH host with no browser, add `--no-browser` to print the URL so you can open it on another device: ```bash banksync login --no-browser ``` ### Log in with an API key For CI, scripts, and agents, authenticate with an API key instead of the browser flow. The CLI validates it against your workspace, then stores it encrypted: ```bash banksync login --api-key bsk_your_api_key_here ``` Only the `bsk_` prefix is validated locally, so a mistyped or non-BankSync key is rejected before anything is stored. You can also skip `login` entirely and set `BANKSYNC_API_KEY` (see below). ## The BANKSYNC\_API\_KEY environment variable For CI, containers, and one-off invocations you do not have to run `login` at all. Set `BANKSYNC_API_KEY` and every command picks it up: ```bash export BANKSYNC_API_KEY="bsk_your_api_key_here" banksync banks list ``` You can also pass `--api-key` on a single command to override whatever is stored: ```bash banksync banks list --api-key bsk_a_different_key ``` Credentials resolve in this precedence order: 1. The `--api-key` flag 2. The `BANKSYNC_API_KEY` environment variable 3. The stored credential for the active profile ## Check who you are `whoami` shows the active credential's workspace, plan, and scopes: ```bash banksync whoami ``` ```text authMethod apiKey workspaceId ws_a1b2c3 workspaceName Acme Inc planTier professional scopes banks:read, feeds:read, jobs:write ``` Add `--json` for a machine-readable version, or run `banksync status` for a one-screen overview that also counts your banks and feeds. ## Log out Remove the stored credential for the active profile: ```bash banksync logout ``` This clears only the local credential; it does not revoke the key. To revoke a key, do it in the dashboard. ## Profiles Profiles let you keep separate credentials and output preferences side by side, for example a personal workspace and a client workspace. Use `--profile` on any command, or set `BANKSYNC_PROFILE`: ```bash banksync login --api-key bsk_client_key --profile client banksync banks list --profile client export BANKSYNC_PROFILE=client banksync banks list ``` Profiles also carry non-sensitive display preferences (default output format, locale, time zone, color, telemetry). Manage them with `banksync config`: ```bash banksync config set output json --profile client banksync config list ``` > **The environment cannot be changed:** Config holds display preferences and profiles only. There is deliberately no base URL or > environment setting: the released CLI always targets production. Attempting to set one is > rejected. ## Where credentials are stored Credentials live in an encrypted file, never in the plaintext config: - Directory: `~/.config/banksync` on macOS and Linux (honoring `XDG_CONFIG_HOME`), and `%APPDATA%\banksync` on Windows. Override with `BANKSYNC_CONFIG_DIR`. - `credentials.json`: your credential, encrypted with AES-256-GCM and written with `0600` permissions (owner read/write only). The encryption key is derived at runtime from a machine-bound value (your host name and user) via scrypt; no key material is written to disk. Because the key is machine-bound, a credentials file copied or backed up to another machine or user account cannot be decrypted there. - `config.json`: profiles and display preferences (no secrets). Secrets never touch the config file or logs. Under `--verbose`, the `X-API-Key` and `Authorization` headers are redacted. > **API keys for headless use:** The browser flow is the quickest way to sign in interactively, but API key auth remains the > recommended path for CI, scripts, and AI agents, which run headless. Pass --api-key or set > BANKSYNC\_API\_KEY. ## Next steps - [API keys](/docs/api/api-keys): create, scope, and rotate keys in the dashboard. - [Scripting and CI](/docs/cli/scripting-and-ci): non-interactive usage and exit codes. - [For agents](/docs/cli/for-agents): hand an agent the CLI plus a key. --- # Output formats > Render BankSync CLI output as a table, JSON, NDJSON, CSV, YAML, or TOON, with a TTY-aware default and column control via --fields and --sort. > Source: https://banksync.io/docs/cli/output-formats Every command that returns data can render it in six formats. The CLI picks a sensible default based on where the output is going, so a human at a terminal gets a readable table and a pipeline gets clean JSON, both with no flag. ## Formats at a glance Choose a format with `-o` (or `--output`). `--json` is a shorthand for `-o json`. | Format | Flag | Best for | | ------ | --------------------- | -------------------------------------------------- | | Table | `-o table` | Humans at a terminal (the default on a TTY) | | JSON | `-o json` or `--json` | Scripts, jq, agents (the default when piped) | | NDJSON | `-o ndjson` | Streaming large pulls, one entity per line | | CSV | `-o csv` | Spreadsheets and data tools | | YAML | `-o yaml` | Config-style, human-readable structured output | | TOON | `-o toon` | Token-efficient tabular output for LLMs and agents | ## The TTY-aware default The default format depends only on whether stdout is a terminal: - Interactive terminal: `table`. - Piped or redirected (not a terminal): `json`. So these two commands render differently even though neither passes a format flag: ```bash banksync banks list # prints a table banksync banks list | jq . # emits JSON, because stdout is a pipe ``` This means `banksync tx list --bank amex | jq` and agent invocations "just work" without a flag. An explicit `-o`/`--json` always wins over the default. > **Color and notices are for humans only:** ANSI color, spinners, footers, and empty-state hints appear only in table output on a terminal. In > any machine format, when piped, under --quiet, or in CI, stdout carries data and nothing else, > so it stays safe to parse. NO\_COLOR and --no-color disable color too. ## Table The table renderer is the only one designed for reading. Text columns are left-aligned, numeric and amount columns are right-aligned, and a single status taxonomy renders the same glyph everywhere: a bank connection, a feed state, and a job status all map onto one set of symbols. ```text ID STATUS TYPE WRITTEN COMPLETED job_9f2a ● completed transactions 412 2m ago job_7c1b ◐ syncing transactions - - job_4d8e ✗ failed balances 0 1h ago 3 jobs · feed fed_123 ``` The glyphs carry meaning even without color: `●` active or ok, `◐` in progress, `○` paused, `✗` failed. On terminals without Unicode they fall back to `*`, `~`, `o`, and `x`. ## JSON and the invariant envelope Every read renders the same top-level shape in `-o json`, whatever the command. Your code can always rely on `.data` and page with `meta`: ```json { "data": [ { "id": "bnk_a1b2", "name": "Chase", "source": "plaid" }, { "id": "bnk_c3d4", "name": "Amex", "source": "plaid" } ], "meta": { "count": 2, "cursor": null, "has_more": null, "schema_version": "1", "api_version": "v1" } } ``` - `data` is the entity or array of entities, with raw API fields (ISO dates, unformatted numbers). It is never humanized: no relative time, glyphs, or color. - `meta.count` is the number of items, `meta.cursor` and `meta.has_more` drive pagination (null when the endpoint does not paginate), `meta.schema_version` is the output-contract version, and `meta.api_version` is the API the CLI speaks. - An empty result is `{"data":[], ...}`, never a human "No banks yet" sentence. Pipe it straight into jq: ```bash banksync banks list --json | jq '.data[] | select(.source == "plaid") | .name' ``` ## NDJSON NDJSON emits one raw entity per line with no envelope, which is ideal for streaming large transaction pulls and for agents consuming incrementally: ```bash banksync tx list --bank amex --all -o ndjson ``` ```text {"id":"txn_1","date":"2026-03-01","description":"UBER","amount":-24.5,"currency":"USD"} {"id":"txn_2","date":"2026-03-01","description":"WHOLE FOODS","amount":-88.12,"currency":"USD"} ``` Each line is a complete JSON object, so it flows into `jq -c`, log processors, or a line-by-line reader without buffering the whole response. ## CSV and YAML CSV writes a header row and one row per entity (nested values are JSON-encoded in the cell), which drops straight into a spreadsheet: ```bash banksync tx list --bank amex -o csv > transactions.csv ``` YAML renders the same envelope as JSON in a config-style layout: ```bash banksync feeds get fed_123 -o yaml ``` ## TOON TOON (Token-Oriented Object Notation) is a compact format built for LLMs and agents. A uniform array of objects becomes a tabular block where the field names appear once in a header and the row count is explicit, which both cuts token usage (roughly 30 to 40 percent versus JSON for tabular data) and makes the schema unambiguous to a model. ```bash banksync feeds list -o toon ``` ```text data[2]{id,name,source,dataType}: fed_1,ANZ Everyday,fiskil,transactions fed_2,Amex,plaid,transactions meta: count: 2 cursor: null has_more: null schema_version: "1" api_version: v1 ``` JSON stays the default machine format; reach for TOON when you are optimizing an agent's token budget over tabular reads. ## Pick your columns with --fields Every renderer accepts `--fields` to select columns by dot-path (arrays support indexing like `errors[0].message`). Discover the default columns for an entity with `banksync schema `. ```bash banksync tx list --bank amex --fields date,description,amount,category banksync banks get bnk_a1b2 --fields id,name,connectionStatus.status ``` ## Sort rows with --sort `--sort` orders rows client-side. Prefix a field with `-` for descending, and pass several comma-separated keys for tie-breaks: ```bash banksync tx list --bank amex --sort -amount banksync jobs list fed_123 --sort -completedAt,status ``` ## Related flags `--no-truncate` keeps wide table cells from being clipped, `--utc` and `--tz` control timestamp display (for example `--tz Australia/Sydney`), and `--locale` sets number formatting. These affect the table renderer only; machine formats always emit raw ISO timestamps and numbers. ## Next steps - [Scripting and CI](/docs/cli/scripting-and-ci): exit codes and non-interactive output. - [For agents](/docs/cli/for-agents): the JSON contract and runtime discovery. - [Syncing and jobs](/docs/cli/syncing-and-jobs): trigger and watch syncs. --- # Syncing and jobs > Trigger a feed sync from the CLI, watch it to completion, and inspect or cancel the sync jobs it produces. > Source: https://banksync.io/docs/cli/syncing-and-jobs A feed moves data from a bank to a destination. Every time it runs it produces a job you can track. The CLI lets you trigger a sync, follow it live, and review or cancel the jobs behind it. ## Trigger a sync Start a sync for a feed by its id: ```bash banksync feeds sync fed_123 ``` By default this is fire-and-forget: the CLI creates the job and immediately prints it, so you can capture the job id and move on. It does not block. ```text ID STATUS TYPE WRITTEN job_9f2a ◐ created transactions 0 ``` ### Sync a date range Pass `--from` and `--to` (both `YYYY-MM-DD`) to sync a specific window: ```bash banksync feeds sync fed_123 --from 2026-01-01 --to 2026-03-31 ``` ### Force past a running sync If a sync is already running for the feed, a new trigger conflicts (exit code 5). Pass `--force` to cancel the in-flight run first, then start yours: ```bash banksync feeds sync fed_123 --force ``` ### Backfill flags Two flags help with backfills and re-syncs: - `--reset-cursors` clears the feed's cursors and dedup state before fetching, for a full re-sync from scratch. - `--skip-dedup` bypasses the per-record dedup guard for this run, so previously seen records are re-emitted. ```bash banksync feeds sync fed_123 --reset-cursors --skip-dedup ``` ## Watch a sync to completion Add `--watch` to poll the job until it reaches a terminal state, with live written-record progress on the spinner: ```bash banksync feeds sync fed_123 --force --watch ``` ```text ⠹ Syncing feed fed_123: 318 written ✓ Sync complete: 412 written ``` On success the final job is printed. On failure the CLI prints the job's error messages and exits nonzero, so a script can branch on it. > **Watch is interactive only:** --watch polls only where notices are allowed, meaning table output on a terminal. When output is > piped, in a machine format, under --quiet, or in CI, the CLI prints the created job and exits 0 > without polling. That keeps stdout deterministic for scripts. To follow a detached job later, use > jobs get --watch below. ## List jobs for a feed See a feed's recent jobs (most recent first), up to 20 by default: ```bash banksync jobs list fed_123 ``` Filter by status and cap the count: ```bash banksync jobs list fed_123 --status failed --limit 5 ``` Valid statuses are `created`, `in_progress`, `paused`, `completed`, `failed`, and `cancelled`. ## Get a job, and re-watch it Fetch a single job by feed id and job id: ```bash banksync jobs get fed_123 job_456 ``` Add `--watch` to poll an already-running job to completion. This uses the same poller as `feeds sync --watch`, so you can detach from a sync and re-attach to the job later: ```bash banksync jobs get fed_123 job_456 --watch ``` ```text ⠸ Job in_progress (207 written) ✓ Job completed (412 written) ``` ## Cancel a job Cancel a created or in-progress job to release the feed lock: ```bash banksync jobs cancel fed_123 job_456 --yes ``` On a terminal, the CLI asks for confirmation first. When prompts are not available (piped, CI, or `--no-input`) it refuses to cancel unless you pass `--yes`, so nothing is cancelled by accident. Cancelling a job that has already finished returns a conflict (exit code 5). ## A common workflow Trigger a backfill, watch it, and inspect any failures: ```bash # Kick off a full re-sync and follow it live banksync feeds sync fed_123 --reset-cursors --watch # Later, review the last few jobs banksync jobs list fed_123 --limit 5 # Drill into a failed one banksync jobs get fed_123 job_456 --json | jq '.data.errors' ``` ## Next steps - [Output formats](/docs/cli/output-formats): tables, JSON, and column control. - [Scripting and CI](/docs/cli/scripting-and-ci): exit codes for conflict and failure. - [Connecting banks](/docs/cli/connecting-banks): link and reauthenticate banks. --- # Connecting banks > Connect a new bank from the CLI through the web app, reauthenticate an existing connection, and search the institution catalog. > Source: https://banksync.io/docs/cli/connecting-banks Linking a bank means completing a provider flow (Plaid, Fiskil, SnapTrade, SaltEdge, and others), some of which are browser-mediated and need a real signed-in session. Rather than reimplement every provider handshake, the CLI hands off to the web app, which already implements them all, then waits for the result. [![Connect a bank through the app](https://cdn.banksync.io/videos/connect-a-bank.poster.66e1177970490809.png)](https://cdn.banksync.io/videos/connect-a-bank.68a0b74986eed503.mp4) [Watch: Connect a bank through the app](https://cdn.banksync.io/videos/connect-a-bank.68a0b74986eed503.mp4) > **Connecting needs a browser and a web session:** banks connect opens an authenticated deep link into the BankSync web app. You need a browser and > an active app session on the same machine. If you are logged out, the app returns you to the > connect flow after sign-in. Headless environments cannot complete a connect; use --no-input to > get the URL and open it elsewhere. ## Connect a new bank ```bash banksync banks connect ``` Here is what happens: 1. The CLI snapshots the banks you already have. 2. It opens your browser to the app's connect flow, at a URL like `https://app.banksync.io/{workspaceId}/banks?connect=1`. 3. You complete the provider flow in the browser with your real session. 4. The CLI polls your workspace until the new bank appears, then prints it. ```text Opened your browser to connect a bank. Waiting for the new connection... ⠹ waiting for a new bank ✓ connected ID NAME SOURCE TYPE STATUS bnk_x9y8 Wells Fargo plaid personal ● active ``` Polling runs for up to three minutes. If it times out, the connection may still have completed in the browser; run `banksync banks list` to check. ### Pre-select a provider or institution Skip a step in the app by pre-seeding the flow: ```bash banksync banks connect --provider plaid banksync banks connect --institution ins_123 ``` ### Headless and non-interactive Under `--no-input` (and automatically when there is no terminal), the CLI does not open a browser or poll. It prints the connect URL and exits, so you can open it on another device: ```bash banksync banks connect --no-input ``` ```text Open this URL to connect a bank: https://app.banksync.io/ws_a1b2c3/banks?connect=1 ``` > **Plan and role still apply:** The connect flow in the app is gated by your role, subscription, and bank limit. A read-only or > capped user who follows the deep link may correctly land on a billing or limit dialog instead of > the connect screen. That is expected: the CLI hands off to the same guarded flow the app uses. ## Reauthenticate a bank When a connection needs re-consent (an expired or revoked provider session), send the user back into the app to fix it: ```bash banksync banks reauth bnk_123 ``` On a terminal this opens the browser to the reauth flow. When there is no browser, or under `--no-input`, it prints the URL to open manually. Reauth uses the same handoff pattern as connect. ## Search the institution catalog Find connectable institutions before you connect, for example to grab an institution id to pre-seed: ```bash banksync banks search chase ``` Narrow by country or provider: ```bash banksync banks search "commonwealth" --country AU banksync banks search chase --provider plaid:us -o json ``` - `--country` takes an ISO country code (for example `US`, `AU`). - `--provider` takes a `providerInstanceId` (for example `plaid:us`). ```text ID NAME COUNTRY PROVIDER ins_3 Chase US plaid:us ins_57 Chase (Business) US plaid:us 2 institutions ``` ## Inspect what you connected After connecting, list banks and drill into accounts: ```bash banksync banks list banksync banks get bnk_x9y8 banksync accounts list bnk_x9y8 ``` ## Next steps - [Syncing and jobs](/docs/cli/syncing-and-jobs): pull data from a connected bank. - [Output formats](/docs/cli/output-formats): tables, JSON, and column control. - [Authentication](/docs/cli/cli-authentication): API keys and profiles. --- # Scripting and CI > Run the BankSync CLI non-interactively in scripts and CI: API key auth, JSON output, stable exit codes, and machine-readable errors. > Source: https://banksync.io/docs/cli/scripting-and-ci The CLI is built to be scriptable first. In a non-interactive context it authenticates from an environment variable, emits JSON, never prompts, and reports failure through stable exit codes and machine-readable errors, so a script or pipeline can branch on results without parsing prose. ## Authenticate without logging in In CI you do not run `login`. Provide the key through `BANKSYNC_API_KEY` and every command uses it: ```bash export BANKSYNC_API_KEY="bsk_your_api_key_here" banksync banks list ``` Store the key as a secret in your CI provider, never in the repository. Use a least-privilege key: a reporting job needs only read scopes. ## Output is JSON when piped Because the default format is JSON whenever stdout is not a terminal, scripts get structured output with no flag. You can still be explicit with `--json`: ```bash banksync banks list | jq '.data | length' banksync tx list --bank amex --json > txns.json ``` The top-level shape is always `{ "data": ..., "meta": ... }`, so `.data` is a reliable path. See [output formats](/docs/cli/output-formats) for the full envelope. ## The CLI never blocks in CI When there is no terminal, the CLI behaves as if `--no-input` were set: it never prompts and never waits. A missing required argument becomes an error, not a hang. `CI=true` is treated as non-interactive too. Destructive commands refuse to run without `--yes`: ```bash banksync feeds delete fed_123 --yes ``` Use `--quiet` to suppress spinners and notices if you want data only, though these already go to stderr and are auto-suppressed when piped. ## Exit codes Every command exits with a stable code that classifies the outcome. Branch on these rather than parsing messages: | Code | Meaning | | ---- | -------------------------------------------------- | | 0 | Success | | 1 | Generic or unexpected error (including 5xx) | | 2 | Invalid usage or bad request (400) | | 3 | Unauthenticated or forbidden (401 or 403) | | 4 | Resource not found (404) | | 5 | Conflict, for example a sync already running (409) | | 6 | Semantic validation failed (422) | | 7 | Rate limited (429) | | 8 | Provider does not support this capability (501) | | 9 | Backend unavailable or consent required (503) | The same map is available at runtime from `banksync commands --json` under `exit_codes`, so an agent or script can read it without hard-coding. ## Machine-readable errors In any non-table format (or when piped), an error is a single JSON object on stderr while stdout stays empty. The shape is stable: ```json { "error": { "code": "conflict", "message": "A sync is already running for this feed.", "status": 409, "hint": "A conflicting operation is in progress. For syncs, pass --force.", "retry_after": 60 } } ``` `code` is a stable snake\_case identifier (never the raw API message), `status` is the HTTP status when there was one, `hint` is a short suggestion, and `retry_after` (seconds) appears on rate-limit errors. On a terminal you instead get a short human `Error` line with a dim hint. ## Retries Idempotent GET requests retry automatically on rate limits (honoring `Retry-After`) and transient network errors, with backoff. Control it with `--max-retries ` or disable it with `--no-retry`. Non-GET requests are never retried. ## A bash script This example reads data and fails cleanly on any error: ```bash #!/usr/bin/env bash set -euo pipefail export BANKSYNC_API_KEY="${BANKSYNC_API_KEY:?set BANKSYNC_API_KEY}" # Fail the script if the CLI exits nonzero; capture JSON for processing. banks=$(banksync banks list --json) echo "$banks" | jq -r '.data[] | "\(.id)\t\(.name)\t\(.connectionStatus.status)"' # Branch on a specific failure class using the exit code. if ! banksync feeds sync fed_123 --watch; then code=$? if [ "$code" -eq 5 ]; then echo "A sync was already running; passing --force" >&2 banksync feeds sync fed_123 --force --watch else echo "Sync failed with exit code $code" >&2 exit "$code" fi fi ``` ## GitHub Actions Install the CLI, authenticate from a secret, and export a report artifact: ```text name: Nightly transactions export on: schedule: - cron: "0 6 * * *" jobs: export: runs-on: ubuntu-latest steps: - name: Install the BankSync CLI run: curl -fsSL https://banksync.io/install.sh | sh - name: Export transactions env: BANKSYNC_API_KEY: ${{ secrets.BANKSYNC_API_KEY }} run: | banksync tx list --bank amex --all -o ndjson > transactions.ndjson - uses: actions/upload-artifact@v4 with: name: transactions path: transactions.ndjson ``` Because the runner is non-interactive, the CLI emits NDJSON without a format flag; the explicit `-o ndjson` here makes the intent clear and stable. ## Next steps - [For agents](/docs/cli/for-agents): the same guarantees, framed for AI agents. - [Output formats](/docs/cli/output-formats): the JSON envelope and NDJSON streaming. - [Telemetry](/docs/cli/telemetry): what is collected and how to opt out in CI. --- # For agents > Give an AI agent the BankSync CLI and an API key: a stable JSON contract, machine-readable errors and exit codes, runtime command and schema discovery, and a raw API escape hatch. > Source: https://banksync.io/docs/cli/for-agents The BankSync CLI is a first-class tool for AI agents, not only for humans. A shell tool plus an API key gives an agent everything it needs to read financial data, manage feeds, and trigger syncs, with a contract stable enough to build on. In practice, a well-designed CLI is often a better agent surface than a bespoke API integration: the output is structured, the errors are machine-readable, and the whole command surface is discoverable at runtime. ## Give your agent the CLI and a key **Wire it up** 1. **Install the CLI** — Drop the standalone binary into the agent's environment with the one-line installer (curl -fsSL https\://banksync.io/install.sh | sh). It is self-contained, so the environment needs no Node or other runtime. See installation. 2. **Provide a scoped API key** — Set BANKSYNC\_API\_KEY in the agent's environment with a least-privilege key created in Settings > Developers. No interactive login is needed. 3. **Let the agent discover the surface** — The agent runs banksync commands --json and banksync schema --json to learn every command, flag, entity, and exit code, then calls commands with --json. ## The contract an agent can rely on - **Stable JSON envelope** — Every read returns { "data": ..., "meta": ... }. The agent can always read .data and page with meta.cursor and meta.has\_more. - **Machine-readable errors** — Failures print one JSON object on stderr and set a stable exit code, so the agent branches on failure without parsing prose. - **No blocking** — In any non-interactive context the CLI never prompts. A missing argument is an error, not a hang. - **Runtime discovery** — commands --json and schema --json expose the entire surface, so an agent needs no out-of-band docs to act. ## The JSON envelope Ask for JSON with `--json` (any pipe also triggers it). Every read has the same top-level shape regardless of the command: ```json { "data": [ { "id": "txn_1", "date": "2026-03-01", "description": "UBER", "amount": -24.5, "currency": "USD" } ], "meta": { "count": 1, "cursor": "eyJvIjoxMDB9", "has_more": true, "schema_version": "1", "api_version": "v1" } } ``` - `data` holds raw entity fields (ISO dates, unformatted numbers), never humanized strings. - `meta.cursor` and `meta.has_more` drive pagination; when they are null the endpoint does not paginate. - `meta.schema_version` is the output-contract version. It is also emitted by `commands --json`, so an agent can assert the contract it was built against. ## Errors and exit codes In JSON mode, an error is a single object on stderr while stdout stays empty: ```json { "error": { "code": "rate_limited", "message": "Too many requests.", "status": 429, "hint": "Rate limited. Retrying automatically; slow down or pass --no-retry.", "retry_after": 60 } } ``` The process exit code classifies the failure so an agent can react programmatically: | Code | Meaning | | ---- | ----------------------------------------------- | | 0 | Success | | 1 | Generic or unexpected error (including 5xx) | | 2 | Invalid usage or bad request (400) | | 3 | Unauthenticated or forbidden (401 or 403) | | 4 | Resource not found (404) | | 5 | Conflict (409) | | 6 | Semantic validation failed (422) | | 7 | Rate limited (429) | | 8 | Provider does not support this capability (501) | | 9 | Backend unavailable or consent required (503) | An agent that gets exit code 3 knows to check the credential; a 5 on a sync means it should retry with `--force`; a 7 means back off. ## Discover the whole surface at runtime An agent does not need to read documentation to act. Two commands expose everything, and neither emits telemetry. ### Command catalog `banksync commands --json` returns the entire command tree, plus the exit-code map and the output-contract version: ```bash banksync commands --json ``` ```json { "cli": "banksync", "output_contract_version": "1", "api_version": "v1", "exit_codes": { "0": "Success", "3": "Unauthenticated or forbidden (401/403)", "5": "Conflict (409)" }, "commands": [ { "id": "transactions list", "summary": "List transactions for a bank or a single account, resolving names or partial ids.", "aliases": ["tx"], "args": [{ "name": "bid", "required": false, "description": "Bank id or name." }], "flags": [ { "name": "from", "type": "option", "required": false, "description": "Start date YYYY-MM-DD." }, { "name": "all", "type": "boolean", "required": false, "description": "Fetch all pages (follows the cursor)." } ] } ] } ``` The agent enumerates command ids, required args, flag names, types, and enum options directly from this output, then constructs a call. ### Entity schema `banksync schema --json` lists the entities, and `banksync schema --json` returns the default columns (the selectable dot-paths for `--fields`): ```bash banksync schema --json banksync schema transaction --json ``` ```json { "data": { "entity": "transaction", "default_columns": ["date", "description", "amount", "currency", "category", "pending"] }, "meta": { "count": 1 } } ``` Known entities include `bank`, `account`, `balance`, `transaction`, `trade`, `holding`, `order`, `loan`, `feed`, `job`, `enrichment`, `integration`, and `institution`. ## Stream large reads with NDJSON For a large pull, `-o ndjson` emits one raw entity per line, which an agent can consume incrementally without buffering the whole response: ```bash banksync tx list --bank amex --all -o ndjson ``` Each line is a complete JSON object, ideal for streaming into a processing loop. ## The raw API escape hatch Any endpoint that does not yet have a dedicated command is reachable through `banksync api`, which reuses the same auth, retries, and output path. It takes an HTTP method and path, an optional body (inline JSON, `@file`, or `-` for stdin), and repeatable `--query` params: ```bash banksync api GET /v1/banks banksync api GET /v1/feeds --query dataType=transactions echo '{"name":"My rule"}' | banksync api POST /v1/enrichments --data - ``` In a machine format, the raw response body is echoed verbatim, so an agent sees exactly what the API returned. This future-proofs the surface: an agent is never blocked by a missing command. ## Non-interactive guarantees > **Deterministic and quiet by default:** When stdout is not a terminal, the CLI emits JSON, never prompts, disables color and spinners, and > sends any notice to stderr, so stdout is byte-clean for parsing. You can force this posture > explicitly with --no-input, --json, and --quiet. Destructive commands still require --yes, > which prevents an agent from deleting or cancelling by accident. ## A worked example An agent asked to summarize spending would typically: ```bash # 1. Confirm the credential and workspace banksync whoami --json # 2. Find the bank by name banksync banks list --json | jq -r '.data[] | select(.name|test("Amex";"i")) | .id' # 3. Pull the quarter's transactions as a stream banksync tx list --bank amex --from 2026-01-01 --to 2026-03-31 --all -o ndjson # 4. On exit code 3, stop and report an auth problem; on 7, back off and retry ``` Each step is structured input and structured output, with a clear exit code, so the agent can chain steps and recover from failure on its own. ## Next steps - [Scripting and CI](/docs/cli/scripting-and-ci): the same guarantees for shell automation. - [Output formats](/docs/cli/output-formats): the envelope, NDJSON, and TOON. - [Telemetry](/docs/cli/telemetry): what usage data is collected and how to disable it. - [MCP server guide](/docs/mcp/overview): the same data exposed to agents over the Model Context Protocol. --- # Telemetry > What anonymous usage analytics the BankSync CLI collects, what it never collects, and how to opt out. > Source: https://banksync.io/docs/cli/telemetry The CLI collects a small amount of anonymous usage analytics to understand which commands are used and where they fail, so the tool can be improved. It is designed to be privacy-preserving by construction: it never sees your account data or your command arguments. ## What is collected One event is recorded per real command, with these fields: - The resolved command name, for example `transactions list` (never the raw arguments you typed). - Whether the command succeeded. - How long it took, in milliseconds. - A mapped error code class on failure, for example `conflict` or `rate_limited` (never the raw error message). - The CLI version. - The authentication method: `apiKey`, `oauth`, or `anonymous`. Events are tied to a random, locally generated identifier stored at `~/.config/banksync/cli-id`. It is not linked to your identity, your key, or your workspace, and the CLI never calls identify or alias. ## What is never collected > **No account data, no arguments:** The CLI never sends financial data, bank or account identifiers, feed or job ids, your API key, or > the arguments you passed. The command name is the resolved id only (for example feeds sync), so > ids on the command line are never transmitted. A built-in scanner also redacts emails, tokens, and > keys before anything is sent. Several commands emit no telemetry at all: `--help`, `--version`, `commands`, `schema`, `config`, and shell autocomplete. Diagnostics and logs are never sent to analytics. ## The first-run notice The first time you run a command that emits telemetry, the CLI prints a one-time notice to stderr describing what is collected and how to opt out, then does not show it again. Because it is written to stderr, it never pollutes stdout, so the disclosure is shown on the first tracked run even when output is piped, in a machine format, or in CI. ## How to opt out Any one of these disables telemetry completely. When disabled, no events are captured. - Set the widely supported `DO_NOT_TRACK` variable: ```bash export DO_NOT_TRACK=1 ``` - Set the BankSync-specific variable to an off value (`0`, `false`, `off`, or `no`): ```bash export BANKSYNC_TELEMETRY=0 ``` - Turn it off persistently in your config (per profile): ```bash banksync config set telemetry off ``` Any of these takes effect immediately on the next command. Environment variables are convenient for CI; the config setting persists across sessions on your machine. ## Environments In local dev and staging builds the CLI uses a no-op analytics provider, so those runs never send anything regardless of settings. The opt-out is honored in every environment. Telemetry flushes with a short timeout, so it can never delay or hang your terminal. ## Next steps - [Authentication](/docs/cli/cli-authentication): profiles and where config and credentials live. - [Scripting and CI](/docs/cli/scripting-and-ci): disabling telemetry in automation. - [Installation](/docs/cli/installation): install and update the CLI. --- # Set up a client portal > Create branded client portals so each client connects their own bank accounts while you manage the feeds and data from one workspace. > Source: https://banksync.io/docs/client-portals/setup If you manage bookkeeping or accounting for multiple clients, a client portal lets each client connect their own bank, card, and investment accounts in a space that carries your name. You stay in control of the data: every portal rolls up into your workspace, so you can build feeds and read every connection from one place. [![Setting up a client portal: the Portals tab, creating the Chen Family portal with a client invitation as editor, the members panel with the pending invitation and copyable link, and the client-side view where the client links their own bank.](https://cdn.banksync.io/videos/client-portals.poster.63297bd37e1e62b1.png)](https://cdn.banksync.io/videos/client-portals.d885025a682a9c7b.mp4) [Watch: Setting up a client portal: the Portals tab, creating the Chen Family portal with a client invitation as editor, the members panel with the pending invitation and copyable link, and the client-side view where the client links their own bank.](https://cdn.banksync.io/videos/client-portals.d885025a682a9c7b.mp4) > **Before you start:** 'Portals are a Pro feature. You need the Professional or Business plan, plus admin or owner access on your workspace. On a lower plan the Portals tab still appears but shows an "Upgrade to unlock" panel instead of the create flow.' ## What a client portal is A portal is a dedicated child workspace that belongs to one client. It keeps that client's accounts isolated from your own and from your other clients, while still sitting under your single subscription. - **Client-owned banks** — Each client connects and authenticates their own accounts inside their portal. - **Rolls up to you** — You and your admins automatically have access to every portal you create. - **One subscription** — Every portal is billed under your plan. No separate signup for the client. ## Step 1: Create a portal **Create your first portal** 1. **Open the Portals tab** — From your workspace, select the Portals tab in the top navigation. 2. **Start a new portal** — Select the New portal card (the dashed tile with the plus icon). 3. **Name and brand it** — In the New portal dialog, type a Portal name (for example, the client's company). Select the icon button to the left of the name to pick an icon that represents the client. 4. **Invite the client now (optional)** — Under Invite a client (optional), enter the client's email and choose a role: Editor or Viewer. You can also leave this blank and invite later. 5. **Create it** — Select Create portal. BankSync opens the new portal and, if you entered an email, sends the invitation right away. ![The Portals tab grid showing three client portal cards (Acme Co with 3 banks and an Active status pill, Smith Family LLC with 1 bank and Active, Bright Capital with no banks yet and an Awaiting client status) plus a dashed New portal tile labeled 'Invite a client to share their bank connections'.](https://cdn.banksync.io/screenshots/portals/portals-list.6ab23e5005205f7b.png "The Portals tab: a card per client plus the New portal tile.") A portal's branding is its name and icon. There is no separate logo or color upload: the name and icon are what your client sees on the invitation and inside their portal. ## Step 2: Set what clients can do Open the portal (select its card) to reach its settings. The **Access** tab holds the **Client permissions** that govern what people invited to this portal can do: - **Clients can connect banks** when on, the client can add their own bank connections. When off, only you (the owner) can add bank connections to this portal. - **Clients can create feeds** lets the client write data into Google Sheets, Notion, or Airtable, including connecting new integrations. Use the **Resources** tab to control what this portal works with. It shows at-a-glance counts (Banks, Feeds, Members, and more), and it is where you pick which of your banks, feeds, and integrations the client portal can see, so a client only ever sees the resources that belong to their engagement. You can also set optional per-portal **Resource limits** such as **Max banks**. Leave a limit blank for no per-portal cap. Per-portal limits always sit under your plan's overall quota. ![The Resources panel of an open client portal: summary count tiles across the top for Banks, Feeds, Members, and Integrations, followed by sections listing the firm's banks, feeds, and integrations with a selection control beside each row to choose which ones this client portal can see (two banks and one Google Sheets integration are selected for the Acme Co portal), and a Resource limits area at the bottom with an optional Max banks field left blank for no per-portal cap.](https://cdn.banksync.io/screenshots/portals/resources-panel.8d80956c9a350180.png "The portal's Resources panel: pick exactly which banks, feeds, and integrations the client portal can see, and set optional per-portal limits.") Changes on these tabs save automatically; a small badge in the dialog header confirms when a change is saved. ## Step 3: Invite the client If you did not invite anyone during creation, open the portal and go to the **Members** tab. **Send an invitation** 1. **Enter the client's email** — In the Invite a client section, type the client's email address. 2. **Choose a role** — Pick Editor or Viewer. Editors can connect banks; viewers can only see status. 3. **Send it** — Select Send invite. The client receives an email with a link to sign in and connect their bank. The invitation appears under **Pending invitations** until the client accepts. From there you can copy the invite link, resend the email, or cancel the invitation. Invitation links expire after 7 days; use the resend action to issue a fresh one. ## What the client sees and does When the client opens the invite link, they sign in and land directly in their own portal. They do not see your other clients or your main workspace. If you gave them the Editor role and left **Clients can connect banks** on, they: 1. Choose to add a bank connection. 2. Authenticate with their bank through the secure connection flow (the same flow described in [Connecting banks](/docs/connecting-banks/connect-a-bank)). 3. See their connected accounts inside the portal once the connection completes. Viewers can sign in to see status but cannot connect banks or create feeds. ## How the data flows back to you Because a portal is a child workspace under yours, you and your admins have access without a separate invitation. Once a client connects an account in their portal, that connection and its data are available to you. You can build and manage feeds that read from the portal's banks, so the client handles authentication while you handle the reporting. For programmatic access across all portals at once (the `scope=family` parameter), see the [developer portals reference](/docs/api/portals). ## Confirm it worked You have set up a portal correctly when: - The portal appears as a card on the **Portals** tab with the name and icon you chose. - The client's invitation shows under **Pending invitations** (before they accept) or the client appears under **Members** (after they accept) on the **Members** tab. - After the client connects an account, the **Resources** tab shows a non-zero **Banks** count. > **Troubleshooting:** 'No Portals tab? The tab is hidden for members below admin (editors and viewers do not see it), inside the browser extension, and when you are already inside a portal: open your main workspace as an admin or owner. Tab shows "Upgrade to unlock" instead of portals? Your current plan does not include portals; upgrade to Professional or Business. Client did not get the email? Check the Pending invitations list, then use the resend action or copy the invite link and share it directly (links expire after 7 days). Client cannot connect a bank? Make sure they have the Editor role and that "Clients can connect banks" is on in the Access tab. "Portal limit reached"? You have used all the portals your plan allows; upgrade or add portal capacity from billing.' ## Next steps Once a client has connected their accounts, set up a feed to send that data into your reporting tools. [Create your first feed](/docs/bank-feeds/creating-first-feed) ## Related guides - [What your clients see](/docs/client-portals/client-experience): the same flow from the invited client's side, including role limits. - [Creating your first feed](/docs/bank-feeds/creating-first-feed): build the feed that reads from your client's newly connected banks. - [Changing your plan](/docs/account-billing/changing-your-plan): portals are included on Professional (5) and Business (20). - [Workspaces and team members](/docs/workspaces/members-and-roles): how roles and membership work in your main workspace. --- # What your clients see > What an invited client sees and can do inside a BankSync client portal, including connecting their own banks. > Source: https://banksync.io/docs/client-portals/client-experience This guide walks through the client portal from the invited client's side: accepting the invitation, signing in, and working inside a focused space that shows their banks and data but none of your firm's account controls. It also explains, for the accountant reading along, how that data reaches you without a second invite. > **Before you start:** This is the client-facing companion to the admin guide. If you are the accountant or bookkeeper setting the portal up, start with the setup guide first: you need to create the portal and send the invitation before a client can do anything here. Portals require the Professional or Business plan on the firm's workspace; the client never needs their own subscription. [![What a client portal looks like from the advisor side and the client side: the portal detail with a pending invitation and copyable link, and the client signing in to connect their own bank into your workspace.](https://cdn.banksync.io/videos/portal-client-view.poster.63297bd37e1e62b1.png)](https://cdn.banksync.io/videos/portal-client-view.99dfde382acf2b0c.mp4) [Watch: What a client portal looks like from the advisor side and the client side: the portal detail with a pending invitation and copyable link, and the client signing in to connect their own bank into your workspace.](https://cdn.banksync.io/videos/portal-client-view.99dfde382acf2b0c.mp4) ## What the client receives When you (the accountant) create a portal and add the client's email, BankSync sends an invitation email right away. The subject line attributes the invite to your firm, in the form `[Your name] invited you to join "[Portal name]"`, and the body names your workspace so the client recognizes who is asking. The email contains a single link to sign in and accept. > **Invitations expire:** Invite links are valid for 7 days. If the client waits too long, the link stops working. The accountant can issue a fresh one from the portal's Members tab using the resend action, or copy the invite link and share it directly. ## How the client accepts and lands in the portal **Accept the invitation** 1. **Open the invite link** — The client selects the link in the invitation email. 2. **Sign in or create an account** — They sign in with the invited email address. A brand-new user creates an account during this step. 3. **Land directly in the portal** — After accepting, BankSync drops the client straight into their portal. They do not pass through your main workspace or see any of your other clients. Accepting the invite makes the client a member of that portal with the role you assigned (Editor or Viewer). The role is fixed on the invitation, so an Editor invite produces an Editor member. ## What a client sees once they are in The portal is a constrained workspace. The client sees their own banks, accounts, and data, but the firm-level controls are removed from the navigation entirely. In Settings, only General and Profile remain. These sections are hidden from a portal client: | Settings section | Visible to client? | Why | | ------------------------------ | ------------------------- | --------------------------------------------------------------------------------- | | General | Yes (read-only name/icon) | Basic workspace info | | Profile | Yes | The client's own account | | Members | No | The accountant manages membership from the parent workspace | | Billing | No | The portal inherits billing from the firm's plan; it has no separate subscription | | Developers | No | API keys for a portal are reserved for the accountant | | Affiliate | No | A firm-level rewards surface | | Delete Workspace (Danger Zone) | No | Only the accountant can delete a portal, from the parent workspace | These are not just hidden links. The routes themselves are guarded: if a client tries to deep-link to `/billing` or `/danger-zone`, BankSync redirects them back to General. ![A client's constrained BankSync portal view: the workspace header shows the portal name 'Acme Co' with a 'Portal' tag beneath it and an 'Editor' role badge, a top tab strip with Banks, Feeds, and Settings, and a Settings sidebar listing only client-visible items grouped as Workspace (General, active) and User (Profile, Security, Connections, Delete Account, Preferences) plus Support. Members, Billing, Developers, Affiliate, and Delete Workspace are absent. The General pane reads 'This portal is named and themed by your accountant. Ask them to change the name or icon.'](https://cdn.banksync.io/screenshots/portals/client-view.cf6ac7e98c82cc46.png "The client's portal: only General and Profile remain in Settings, with the firm-level tabs gone.") > **The Portal label in the switcher:** 'If a client belongs to more than one workspace, the portal entry in the workspace switcher carries a "Portal" tag so they can tell a portal apart from a regular workspace at a glance.' ### Settings are read-only for clients A client cannot rename the portal or change its icon. The General settings page shows the message: "This portal is named and themed by your accountant. Ask them to change the name or icon." If a client (even one promoted to admin inside the portal) tries to rename it through the API, the request is rejected with an "only the accountant" error. The same rule blocks portal clients from inviting new members. ## Connecting their own bank accounts Whether a client can add a bank depends on the **Clients can connect banks** setting the accountant controls on the portal's Access tab. **Connect a bank (when allowed)** 1. **Open the Banks tab** — From inside the portal, the client selects the Banks tab. 2. **Add a new connection** — They choose the option to add a bank connection. This appears only when bank creation is enabled for portal members. 3. **Authenticate with their bank** — They sign in to their institution through the same secure connection flow described in' ' Connecting banks. 4. **See the connected accounts** — Once the connection completes, the accounts appear inside the portal's Banks tab. > **When bank creation is turned off:** 'If the accountant disables "Clients can connect banks," the client still sees the Banks tab and any accounts already connected, but the add-a-new-connection control is removed. A direct attempt to start a connection is rejected by the server with a "does not allow" message. The client cannot add banks; the accountant adds them instead.' ## Client can / cannot, by role Roles are scoped to the portal. A few capabilities also depend on the portal-level toggles the accountant sets. | Capability | Editor | Viewer | | ------------------------------------------------------------------------------------- | ------ | ------ | | Sign in and see the portal's banks and data | Yes | Yes | | Connect a new bank (when "Clients can connect banks" is on) | Yes | No | | Create feeds into Sheets, Notion, or Airtable (when "Clients can create feeds" is on) | Yes | No | | View account status and balances | Yes | Yes | | Rename or re-icon the portal | No | No | | See Members, Billing, Developers, Affiliate, or Delete Workspace | No | No | | Invite other members to the portal | No | No | Editor and Viewer alike are blocked from the firm-level settings and from renaming the portal. The Editor / Viewer split governs whether the client can act on data (connect banks, create feeds), not whether they can touch firm controls. ## For the accountant: how the data flows back to you A portal is a child workspace under yours, so you and your admins already have access to it without any second invitation. The moment a client connects a bank in their portal, that connection and its data are available to you. You can build and manage feeds that read from the client's banks: the client handles authentication, you handle the reporting. From your main workspace you can see a portal's banks marked "Managed by the client in \[Portal name]," and you reconnect or disconnect by opening the portal. For reading or managing every portal at once programmatically, use the `scope=family` parameter described in the developer portals reference. ## Confirm it worked The client experience is set up correctly when, after the client accepts the invite: - They land directly in the portal and see the **Banks** tab with their accounts (or an empty Banks tab ready for a connection). - The Settings navigation shows only **General** and **Profile**: no Members, Billing, Developers, Affiliate, or Delete Workspace. - If the client belongs to more than one workspace, the portal carries a **Portal** tag in the workspace switcher. - Back in your main workspace, the client appears under **Members** on the portal (not just **Pending invitations**), and once they connect an account the portal's **Resources** tab shows a non-zero **Banks** count. ## Troubleshooting > **Common client-side snags:** 'Invite link not working? It may have expired (7-day limit); ask the accountant to resend it. Client signed in but sees a different workspace? They may have multiple workspaces: look for the entry tagged "Portal" in the switcher. Client cannot add a bank? Confirm the accountant gave them the Editor role and that "Clients can connect banks" is on in the portal\\'s Access tab. Client wants the portal renamed? Only the accountant can do that, from the parent workspace; the General page is read-only for clients by design.' ## Next steps - **Set the portal up** — Configure permissions, branding, and invites from the admin side. - **Automate across clients** — Read every portal at once with scope=family. [Set up a client portal](/docs/client-portals/setup) ## Related guides - [Set up a client portal](/docs/client-portals/setup): the admin-side flow for creating the portal, permissions, and invites. - [Connecting banks](/docs/connecting-banks/connect-a-bank): the secure connection flow your clients go through inside the portal. - Developer portals reference: programmatic access across every portal at once with scope=family. --- # Connect a bank > Search for your bank, sign in through your provider, choose which accounts to share, and confirm the connection in BankSync. > Source: https://banksync.io/docs/connecting-banks/connect-a-bank Connecting a bank is the first thing you do in BankSync, and it works the same way no matter where you bank. You search one global list of institutions, BankSync routes you to the right open-finance provider automatically, you sign in through that provider's secure window, and your accounts appear on the Banks page ready to power a feed. > **Your credentials stay with your bank:** BankSync connects through trusted providers (Plaid, Fiskil, and SnapTrade depending on your institution and account type). You enter your bank login in the provider's own secure window, never in BankSync, and BankSync never sees or stores your bank password. > **Before you start:** You need a BankSync account and your online banking login (username and password, plus any two-factor method your bank uses such as an SMS code). It helps to confirm you can sign in to your bank's website directly first. [![The full bank connection flow in the BankSync app: opening the Connect a new bank tile on the Banks page, searching for Chase in the Connect Bank dialog, signing in through the provider's secure window, the Authorization Successful confirmation, and the new Chase bank card appearing on the Banks page.](https://cdn.banksync.io/videos/connect-a-bank.poster.66e1177970490809.png)](https://cdn.banksync.io/videos/connect-a-bank.68a0b74986eed503.mp4) [Watch: The full bank connection flow in the BankSync app: opening the Connect a new bank tile on the Banks page, searching for Chase in the Connect Bank dialog, signing in through the provider's secure window, the Authorization Successful confirmation, and the new Chase bank card appearing on the Banks page.](https://cdn.banksync.io/videos/connect-a-bank.68a0b74986eed503.mp4) ## The universal connection flow There is no region picker to choose first. You type your bank's name, BankSync detects the correct country and provider, and the matching secure login opens. The same four moves apply to a US checking account, a Canadian credit card, an Australian bank, or a brokerage: **Connect any institution** 1. **Open the Banks page and add a bank** — Select Banks from the navigation, then click the dashed "Connect a new bank" tile. The "Connect Bank" dialog opens with the subtitle "Search and connect your financial institution". 2. **Search and pick your institution** — Type at least 2 characters into the "Search institutions" box. Results stream in as cards showing the institution name, supported account types, a country flag, and the provider. Click the card that matches yours. 3. **Sign in and give consent** — The provider's secure window opens automatically. Confirm the institution, enter your online banking credentials, complete any verification step, and tick the accounts you want to share. Account selection happens inside the provider window, not in BankSync. 4. **Land back in BankSync** — When the provider finishes, BankSync shows an "Authorization Successful" dialog. Click "Continue" and your bank appears as a card on the Banks page with the accounts you selected. > **Narrow the search if you need to:** 'Click the filter button next to the search box to limit results by Provider (All, Plaid, SnapTrade, SaltEdge, Fiskil) or by Country. Leave both on "All" when you are not sure. If few results come back, a "Not finding your bank?" prompt with a "Request this bank" button appears.' ## How BankSync routes to a provider BankSync picks the provider behind the scenes based on the institution's country and the type of account. You never select a provider yourself, but it helps to know which one handles your connection so you can read the right region-specific guide for the finer details. | Region / Type | Provider | What you can connect | | -------------------------- | ------------------------- | ------------------------------------------------------------------------------------- | | United States | Plaid | Checking, savings, credit card, loan, and mortgage accounts at US banks | | Canada | Plaid | Checking, savings, and credit card accounts at Canadian banks | | Australia | Fiskil (CDR open banking) | Bank and credit card accounts at Australian institutions via the Consumer Data Right | | Brokerages and investments | SnapTrade | Investment accounts: holdings, balances, and trade activity from supported brokerages | > **One institution can route more than one way:** 'A bank that offers both everyday accounts and a brokerage may appear more than once in search, routed to different providers. Pick the card whose account types and provider match what you want to connect, then connect the other separately if you need both.' > **How many banks can I connect?:** 'Your plan caps the number of connected banks in a workspace: 1 on Starter, 5 on Standard, 15 on Professional, 30 on Business, and unlimited on Enterprise (the Free plan allows 0). If you hit the cap, remove a bank you no longer need or upgrade. See Managing your plan for details.' ## Provider-specific guides The flow above is identical everywhere, but each region and account type has a few details worth knowing (supported account types, how account selection looks, and common gotchas). Pick the guide that matches what you are connecting: - **US banks** — Connect US checking, savings, and credit cards through Plaid. - **Canadian banks** — Connect Canadian accounts through Plaid, including country-code tips. - **Australian banks** — Connect AU institutions through Fiskil and CDR open banking. - **UK banks** — Connect UK institutions through Salt Edge and Open Banking. - **European banks** — Connect banks across 30 EEA countries through Salt Edge and PSD2. - **Brokerages** — Connect investment accounts through SnapTrade for holdings and trades. * [Connect US banks](/docs/connecting-banks/us-banks) * [Connect Canadian banks](/docs/connecting-banks/canadian-banks) * [Connect Australian banks](/docs/connecting-banks/australian-banks) * [Connect UK banks](/docs/connecting-banks/uk-banks) * [Connect European banks](/docs/connecting-banks/european-banks) * [Connect brokerages and investment accounts](/docs/connecting-banks/brokerages) ## Confirm it worked You have connected your bank successfully when: - The institution appears as a card on the Banks page, no longer just the "Connect a new bank" tile. - The accounts you selected in the provider window are linked to that bank. - The bank shows an active state, not a "Requires re-authentication" or "Scheduled for deletion" label. ## Troubleshooting > **Common issues:** 'Institution not found: try the parent company or full legal name, or use "Request this bank". Country unavailable: if your region isn\\'t supported yet, BankSync shows a waiting-list form so you can register interest. Connection failed or accounts missing: confirm you can sign in on your bank\\'s website, then reconnect from the bank\\'s card and re-select the accounts. Needs re-authentication: open the bank and use "Reconnect / Add Accounts" to refresh consent.' ## Next steps With a bank connected, build a feed that syncs its data to your spreadsheet or database. [Create your first feed](/docs/bank-feeds/creating-first-feed) ## Related guides - [Creating your first feed](/docs/bank-feeds/creating-first-feed): route the connected bank's data into your spreadsheet or database. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): refresh a connection that has expired or needs re-authentication. - [Removing a bank](/docs/connecting-banks/removing-a-bank): disconnect an institution you no longer need, with a grace window to undo. - [Getting started](/docs/getting-started/quickstart): the full setup overview from first sign-in to first sync. --- # Connecting US banks > Connect US bank, card, loan, and investment accounts through Plaid, including OAuth bank logins and account selection. > Source: https://banksync.io/docs/connecting-banks/us-banks US banks connect to BankSync through Plaid, a trusted banking provider that supports thousands of US institutions. You search for your bank, sign in through Plaid's secure window (large banks send you to their own bank-hosted login), pick the accounts you want to share, and the connected bank then appears on your Banks page ready to power a feed. > **Your credentials stay with your bank:** You enter your online banking login in Plaid's secure window (or your bank's own login page), never in BankSync. BankSync receives only the read access you approve and never sees or stores your bank password. > **Before you start:** You need a BankSync account and your US online banking login (username, password, and any verification method your bank uses, such as an SMS or authenticator code). Confirm you can sign in on your bank's website first. If sign-in fails there, it will also fail in the connect flow. [![Connecting a US bank through Plaid: the Connect a new bank tile, searching for Chase, Plaid's secure sign-in window, the Authorization Successful confirmation, and the connected Chase card on the Banks page.](https://cdn.banksync.io/videos/connect-a-bank.poster.66e1177970490809.png)](https://cdn.banksync.io/videos/connect-a-bank.68a0b74986eed503.mp4) [Watch: Connecting a US bank through Plaid: the Connect a new bank tile, searching for Chase, Plaid's secure sign-in window, the Authorization Successful confirmation, and the connected Chase card on the Banks page.](https://cdn.banksync.io/videos/connect-a-bank.68a0b74986eed503.mp4) ## Search for your US bank You do not pick a region first. Type your bank's name and BankSync detects that it is a US institution and routes it through Plaid automatically. **Find your institution** 1. **Open the Banks page** — Select Banks from the navigation. This is where all your connected institutions live. 2. **Start a new connection** — Select the "Connect a new bank" tile (the dashed card with the plus icon). The "Connect Bank" dialog opens with the subtitle "Search and connect your financial institution". 3. **Type your bank name** — In the "Search institutions" box, enter at least 2 characters (for example "Chase", "Bank of America", "Wells Fargo", "Citibank", or "TD Bank"). Matching institutions appear as cards as you type. 4. **(Optional) filter to Plaid** — Click the filter button next to the search box, then under Provider select "Plaid" and under Country select "US" to restrict results to US Plaid institutions. 5. **Select your institution** — Click the matching card. A "Preparing connection..." overlay appears with the message "The secure login window will open shortly", then the Plaid window opens. ![The BankSync Connect Bank dialog searching for Chase, showing US institution result cards (Chase, Chase Investments, JPMorgan Chase Bank, Chase Auto) with supported account-type tags, a US flag, and the provider name (Plaid or SnapTrade).](https://cdn.banksync.io/screenshots/banks/connect-search.53262ba3c1a27f9a.png "Searching for a US institution in the Connect Bank dialog.") Each result card shows the institution name, a US flag with the provider name (Plaid), and tags for the account types that institution supports. | Account type tag | Covers | | ---------------- | --------------------------------------------------------------------- | | Checking | Everyday checking accounts | | Savings | Savings and money-market accounts | | Credit Card | Credit card balances and charges | | Loan | Personal, auto, and student loans | | Mortgage | Home loans | | Investment | Brokerage and investment accounts, where the institution exposes them | > **What US institutions can share:** Most US banks expose checking, savings, credit cards, and loans through Plaid. Investment and brokerage data is available only where the institution itself supports it, so the Investment tag will not appear on every card. Some institutions also limit individual products: certain credit cards (for example some store or co-branded cards) and many business cards are excluded by the bank at its data-sharing layer, so they may not appear for selection even though the card shows in your bank's own login. ## Sign in through Plaid After you select the institution, Plaid's secure window takes over. The exact screens depend on your bank. **Complete the secure login** 1. **Confirm the institution** — Plaid shows the bank you picked. Confirm it is correct to continue. 2. **Sign in** — For most banks you enter your online banking username and password directly in the Plaid window. Large US banks use OAuth: instead of typing your password into Plaid, you are handed to the bank's own hosted login page (the same one you use on the bank's website) to sign in there. 3. **Complete verification** — If your bank requires it, complete the multi-factor step (an SMS code, an email code, a security question, or an authenticator approval). OAuth banks handle this on their own page. 4. **Approve access** — Confirm that you allow read-only access to your account data. OAuth banks show their own account-selection and approval screen before returning you to BankSync. > **OAuth banks open their own login window:** When a US bank uses OAuth, the login, verification, and account approval all happen on the bank's own page, not inside Plaid's form. This is expected and is more secure: your password is entered only on your bank's site. After you approve, the bank hands you back to BankSync automatically. ## Choose which accounts to share You select which accounts to connect inside the Plaid (or bank-hosted) window, not in BankSync. **Pick your accounts** 1. **Review the account list** — Plaid lists the accounts at that institution: checking, savings, credit cards, loans, and any investment accounts the bank exposes. 2. **Select the ones you want** — Tick only the accounts you want to sync (for example just your business checking and a credit card). Only the accounts you select are shared with BankSync. 3. **Finish** — Confirm your selection to close the secure window and return to BankSync. > **Connecting more accounts later:** 'If you already have a connection to the same US bank, BankSync shows an "Existing Connections" screen instead of a fresh login. Choose "Create New Connection" to link a separate set of accounts (Plaid supports multiple connections per bank), or "Add Accounts" next to an existing connection to share more accounts on it. "Reconnect" appears when a connection needs re-authentication.' ## Confirm it worked When the secure window finishes, BankSync shows an "Authorization Successful" dialog confirming "You have successfully authorized access to your bank account." Click "Continue". You have connected your US bank successfully when: - The institution appears as its own card on the Banks page, no longer just the "Connect a new bank" tile. - The accounts you selected in the Plaid window are listed under that bank. - The bank shows an active state, not a "Requires re-authentication" or "Scheduled for deletion" label. ## Troubleshooting | Symptom | What it usually means | What to do | | ---------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bank not in search results | The institution is not yet in coverage, or you searched a nickname | Try the full legal name or parent company. When few results return, a "Not finding your bank?" prompt appears with a "Request this bank" button. On a no-match, "No banks found" shows the same button. Submit the request so the team can look into adding it. | | Login or MFA loops | The bank is repeatedly asking for credentials or a code | Confirm you can sign in on the bank's own website first. For OAuth banks, make sure pop-ups are allowed so the bank's login page can open, then retry. Wait out any temporary lockout from too many attempts before reconnecting. | | An account or card is missing after connecting | The bank excludes that specific product at its data-sharing layer | Some credit cards and most business cards are not shareable even though they show in your bank's login. Re-run the connection and check whether the account is offered in the selection list. If it never appears, that product is not available through the bank's data sharing. | | Investment account did not connect | The institution does not expose investments through Plaid | If the result card has no Investment tag, that bank does not share brokerage data here. Search for the brokerage arm instead and connect it through SnapTrade; see [Connecting brokerages](/docs/connecting-banks/brokerages). | | "Requires re-authentication" on the bank card | The bank's consent expired or credentials changed | Open the bank on the Banks page and use "Reconnect / Add Accounts" to refresh access. Reconnecting keeps your accounts, history, and feeds intact; see [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank). | > **Ticket email and login email can differ:** 'If an account you expect is missing, double-check you signed in to the right bank login. The email you use for BankSync is separate from your online banking login, and a bank can hold accounts under more than one profile.' ## Next steps With your US bank connected, the next step is to build a feed that syncs its data to your spreadsheet or database. [Create your first feed](/docs/bank-feeds/creating-first-feed) ## Related guides - [Connect a bank](/docs/connecting-banks/connect-a-bank): the general connection flow for every country and provider. - [Connecting brokerages](/docs/connecting-banks/brokerages): US investment accounts that connect through SnapTrade instead of Plaid. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): fix a connection flagged "Requires re-authentication" without losing history. - [Managing feeds](/docs/bank-feeds/managing-feeds): keep syncs healthy once the bank is connected. --- # Connecting Canadian banks > Connect Canadian chequing, savings, credit, and investment accounts through Plaid. > Source: https://banksync.io/docs/connecting-banks/canadian-banks Canadian institutions connect to BankSync through Plaid, which covers Canadian banks alongside the United States. The flow is the same as connecting any other bank: search for your institution, sign in through Plaid's secure window, pick the accounts you want to share, and the bank appears on your Banks page ready to power a feed. > **Before you start:** You need a BankSync account and your Canadian online banking login (card number or username, password, plus any verification step your bank uses such as an SMS or email code). Confirm you can sign in to your bank's website directly first. If the institution you want is a brokerage or investment platform rather than a bank, see Connecting brokerages instead, since those connect through SnapTrade. > **Your credentials stay with your bank:** BankSync connects Canadian banks through Plaid. You enter your bank login in Plaid's own secure window, not in BankSync. BankSync never sees or stores your bank password. [![The bank connection flow Canadian banks follow too: searching for your bank in the Connect Bank dialog, signing in through Plaid's secure window, and the connected bank card appearing on the Banks page.](https://cdn.banksync.io/videos/connect-a-bank.poster.66e1177970490809.png)](https://cdn.banksync.io/videos/connect-a-bank.68a0b74986eed503.mp4) [Watch: The bank connection flow Canadian banks follow too: searching for your bank in the Connect Bank dialog, signing in through Plaid's secure window, and the connected bank card appearing on the Banks page.](https://cdn.banksync.io/videos/connect-a-bank.68a0b74986eed503.mp4) ## Open Banks and add a bank **Start the connection** 1. **Go to the Banks page** — Open BankSync and select Banks from the navigation. This is where all your connected institutions live. 2. **Click 'Connect a new bank'** — Select the dashed "Connect a new bank" tile (the card with the plus icon). The "Connect Bank" dialog opens with a "Search and connect your financial institution" subtitle and a search box. ## Search for and select your Canadian bank You do not choose a region first. Type your bank's name and BankSync searches across every supported country and provider at once, then routes Canadian results to Plaid automatically. **Find your bank** 1. **Type your bank name** — In the "Search institutions" box, enter at least 2 characters of your bank's name (for example "RBC", "TD", "Scotiabank", or "BMO"). Matching institutions appear as cards as you type. 2. **(Optional) narrow to Canada** — Click the filter button next to the search box to open Filters, then under Country select the 🇨🇦 CA chip. You can also leave Provider on "All" or set it to Plaid. Leave both on "All" if you are not sure. 3. **Read each result card** — Each Canadian result shows the institution name, the account types it supports, and a 🇨🇦 CA flag next to the provider name (Plaid). Use these to confirm you are picking the right institution. 4. **Select your institution** — Click the matching card. BankSync detects that the institution is Canadian and selects Plaid for you, so there is no separate region step. A "Preparing connection..." overlay appears and Plaid's secure login window opens shortly. ![The BankSync Connect Bank dialog searching for RBC, showing Canadian institution result cards (Royal Bank of Canada, TD Canada Trust, Scotiabank, BMO Bank of Montreal) with chequing, savings, and credit-card account-type tags, a Canadian flag, and the Plaid provider.](https://cdn.banksync.io/screenshots/banks/connect-search-ca.fbe88a2931946b02.png "Searching for a Canadian institution in the Connect Bank dialog.") > **Picking the right TD entity:** 'Some institutions appear more than once (for example a Canadian retail bank versus a U.S. arm of the same brand). Check the 🇨🇦 CA flag on the card so you select the Canadian institution, not its U.S. counterpart.' ## Supported Canadian account types BankSync surfaces whatever account types Plaid exposes for the institution. The result card lists them so you know what you can sync before you connect. | Account type | Card label | Notes for Canadian institutions | | --------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Chequing | Checking | Day-to-day transaction accounts. Most common Canadian connection. | | Savings | Savings | High-interest and regular savings accounts. | | Credit card | Credit Card | Visa, Mastercard, and store cards where the issuer shares them through Plaid. | | Investment | Investment | Available where the bank shares investment holdings through Plaid. For standalone brokerages, connect through SnapTrade instead. | | Loan / Mortgage | Loan / Mortgage | Shown only where the institution exposes loan or mortgage data. | > **Where account selection happens:** You choose which accounts to share inside Plaid's window, not in BankSync. After you sign in, Plaid lists your accounts and lets you tick the ones you want (for example just your chequing and credit card). Only the accounts you select are shared with BankSync. ## Sign in and give consent After you select the institution, Plaid's own secure window opens. Confirm the institution, enter your Canadian online banking credentials, complete any verification step (such as an SMS or email code), and select the accounts to share. If you already have a connection to the same institution, BankSync shows an "Existing Connections" screen instead of opening a fresh login: - Choose "Create New Connection" to link a separate set of accounts (Plaid supports multiple connections to the same bank). - Choose "Add Accounts" next to an existing connection to share more accounts on that same connection. - Choose "Reconnect" if a connection is flagged as needing re-authentication. > **Multi-currency CAD and USD accounts:** Many Canadian banks offer both CAD and USD accounts (for example a USD chequing or USD credit card). Each currency is usually a separate account in Plaid's account list, so tick every currency you want to sync. When you later build a feed, each account keeps its own currency in the synced data, so a USD account is not converted to CAD for you. ## Confirm it worked When Plaid's window finishes, BankSync shows an "Authorization Successful" dialog confirming "You have successfully authorized access to your bank account." and "Your bank has been added and transactions will be synced automatically." Click "Continue". You have connected your Canadian bank successfully when: - The institution appears as a card on the Banks page (no longer just the "Connect a new bank" tile). - The card shows the 🇨🇦 CA flag and the accounts you selected in Plaid's window are linked to that bank. - The bank shows an active state rather than a "Requires re-authentication" or "Scheduled for deletion" label. ## Troubleshooting > **Bank not listed:** 'If your Canadian bank does not appear, try the full legal name or the parent brand, and confirm the Country filter is on "All" or 🇨🇦 CA rather than another country. When few results come back, a "Not finding your bank?" prompt with a "Request this bank" button appears: submit it and the team will look into adding coverage.' > **Accounts missing after connecting:** 'If an account you expected is not linked, it usually means it was not ticked in Plaid\\'s selection screen, or the bank does not share that account type through Plaid. Open the bank\\'s card on the Banks page and use "Reconnect / Add Accounts" to reopen Plaid and select the missing accounts. If a USD or CAD variant is missing, check that you selected every currency.' > **This is a brokerage, not a bank:** 'Standalone Canadian investment and brokerage platforms connect through SnapTrade, not Plaid. If you searched for a brokerage and the connection does not behave like a bank, follow Connecting brokerages instead.' > **Connection failed or needs re-authentication:** 'Confirm you can sign in on your bank\\'s own website first, then reconnect from the bank\\'s card on the Banks page. If the bank shows "Requires re-authentication", open it and use "Reconnect / Add Accounts" to refresh consent with Plaid.' ## Next steps With your Canadian bank connected, the next step is to build a feed that syncs its data to your spreadsheet or database. [Create your first feed](/docs/bank-feeds/creating-first-feed) ## Related guides - [Connecting brokerages](/docs/connecting-banks/brokerages): standalone Canadian investment platforms connect through SnapTrade, not Plaid. - [Connect a bank](/docs/connecting-banks/connect-a-bank): the general connection flow across all countries. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): refresh a connection that needs re-authentication without losing history. - [Managing feeds](/docs/bank-feeds/managing-feeds): keep syncs healthy once the bank is connected. --- # Connecting Australian banks > Connect Australian bank accounts through Fiskil and the Consumer Data Right (CDR) open banking consent flow. > Source: https://banksync.io/docs/connecting-banks/australian-banks Australian banks connect to BankSync through Fiskil using the Consumer Data Right (CDR), Australia's Open Banking framework. You search for your bank, complete a CDR consent flow in your bank's own secure window, and choose exactly which accounts and data you want to share. This guide covers the AU-specific parts of the flow on top of the general [Connect a bank](/docs/connecting-banks/connect-a-bank) steps. > **Before you start:** You need a BankSync account and your online banking login for the Australian institution you want to connect (plus any verification step your bank uses, such as an SMS one-time code). The connection happens inside your bank's secure CDR window, so make sure you can sign in to your bank directly first. > **CDR keeps you in control:** Under the Consumer Data Right you authorise an accredited data recipient to access specific banking data for a set period. You enter your bank login in the bank's own CDR window, never in BankSync, and you can review or revoke the consent at any time. [![Connecting an Australian bank: searching for CommBank, reviewing the CDR pre-consent summary, authorizing with Fiskil, and landing on a connected CommBank card.](https://cdn.banksync.io/videos/connect-cdr-au.poster.0bb77889704c734f.png)](https://cdn.banksync.io/videos/connect-cdr-au.10a5a3bade91d1c7.mp4) [Watch: Connecting an Australian bank: searching for CommBank, reviewing the CDR pre-consent summary, authorizing with Fiskil, and landing on a connected CommBank card.](https://cdn.banksync.io/videos/connect-cdr-au.10a5a3bade91d1c7.mp4) ## Search for your Australian bank You do not pick a country first. Type your bank's name and BankSync searches every supported provider and region at once, then routes Australian institutions through Fiskil automatically. **Find your institution** 1. **Open the Banks page** — Select Banks from the navigation, then click the dashed "Connect a new bank" tile. The "Connect Bank" dialog opens with a search box. 2. **Type your bank name** — In the "Search institutions" box, enter at least 2 characters (for example "CommBank", "Westpac", "NAB", or "ANZ"). Matching institutions appear as cards as you type. 3. **(Optional) narrow the results** — Click the filter button next to the search box and set Provider to "Fiskil" or Country to "Australia" to show only Australian institutions. 4. **Check the result card carefully** — Each card shows the institution name, the account types it supports, a country flag, and the provider name. Pick the exact entity you bank with (see the CommBank vs CommBiz note below). 5. **Select your institution** — Click the matching card. BankSync detects the Australian region and Fiskil provider automatically, shows a "Preparing connection..." overlay, and opens the secure CDR consent window shortly. ![The BankSync Connect Bank dialog searching for CommBank, showing Australian institution result cards (Commonwealth Bank, ANZ, NAB, Westpac) with account-type tags, an Australian flag, and the Fiskil provider (CDR open banking).](https://cdn.banksync.io/screenshots/banks/connect-search-au.109f666e4b706f12.png "Searching for an Australian institution, connected through Fiskil and the CDR.") > **CommBank and CommBiz are separate institutions:** 'Commonwealth Bank\\'s personal banking (NetBank / "CommBank") and its business banking ("CommBiz") are two distinct institutions in the bank search. Connect the one that actually holds the accounts you want. If you bank with both, connect each separately, they do not share a single consent.' ## Complete the CDR consent flow After you select an Australian institution, your bank's own CDR window opens. The exact screens are controlled by your bank, but the consent always asks you to confirm three things: what data you are sharing, which accounts it covers, and for how long. **Authorise data sharing** 1. **Confirm the data you are sharing** — The consent screen lists the data types being requested, typically account details, balances, and transactions. Review them before continuing. 2. **Sign in to your bank** — Enter your online banking identifier and complete your bank's verification step (often a one-time code sent by SMS). You do this inside the bank's CDR window, not in BankSync. 3. **Select which accounts to share** — Tick only the accounts you want BankSync to access. Accounts you leave unticked are never shared. 4. **Set the consent duration** — Choose how long the consent lasts (CDR consents are time-limited, for example up to 12 months). When it reaches the end of that period it lapses and must be renewed. 5. **Confirm and return** — Approve the consent. The CDR window closes and returns you to BankSync. ### What data Australian banks share | Data type | Shared via CDR | Notes | | --------------- | -------------------------------- | ------------------------------------------------------------------------------------------ | | Account details | Yes | Account name, type, and identifiers for the accounts you select. | | Balances | Yes | Current and available balance. | | Transactions | Yes | Posted transactions within the history the bank exposes (see the history note below). | | Account types | Transaction and deposit accounts | Everyday, savings, offset, and credit/card accounts where the bank exposes them under CDR. | > **How fresh is CDR data?:** Balance and transaction data delivered through CDR refreshes roughly once a day. BankSync's hourly scheduler still checks your feed, but Australian banks update their CDR feed on an approximately daily cadence, so new transactions can take up to a day to appear regardless of how often you sync. > **Some banks only expose a limited history window:** A number of Australian banks publish only a limited window of transaction history through CDR (for example around the last six months), even on accounts you have held for years. This is a bank and CDR limit, not a BankSync setting: BankSync delivers 100% of what the bank makes available. Re-consenting does not extend it. For older records, export a statement directly from your bank's online banking. ## Confirm it worked When the CDR window finishes, BankSync shows an "Authorization Successful" dialog. Click "Continue". You have connected your Australian bank successfully when: - The institution appears as a card on the Banks page (no longer just the "Connect a new bank" tile). - The accounts you ticked in the CDR window are linked to that bank. - The bank shows an active state, not a "Requires re-authentication" or "Scheduled for deletion" label. With the bank connected and active, you can build a feed to sync its transactions and balances to your spreadsheet or database. See [Create your first feed](/docs/bank-feeds/creating-first-feed). ## Troubleshooting > **Common Australian-bank issues:** Only limited history is available: this is a bank/CDR limit on the transaction window the institution exposes, not a BankSync setting. Re-connecting will not reach back further; export older records from your bank instead. Consent expired or syncs stopped returning data: CDR consents are time-limited and lapse at the end of their period, so re-authorise the connection (see Reconnecting a bank below). Wrong accounts connected: the personal vs business entities (such as CommBank and CommBiz) are separate institutions; connect the one that holds the accounts you need. Connection failed: confirm you can sign in to your bank's website directly, then try the connection again from the Banks page. When a CDR consent lapses or your bank flags the connection, the bank's card shows a "Requires re-authentication" state. Open the bank and use "Reconnect / Add Accounts" to start a fresh CDR consent. Because reconnecting an Australian bank is a re-consent, your bank's CDR window asks you to select accounts again: tick every account you still want to share, or it will drop out of the new consent. Your already-synced history and your feeds are untouched either way. See [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank) for the full flow. ## Managing and withdrawing your consent Once connected, you can view, renew, and withdraw your CDR consents from **Settings → Data sharing**. When you send this data to a destination such as a spreadsheet or Notion, BankSync first asks you to confirm a disclosure: data that leaves BankSync is no longer regulated under the CDR and is instead governed by the Privacy Act 1988 and the destination's own privacy policy. Withdrawal takes effect immediately. See [Managing your CDR consents and data sharing](/docs/connecting-banks/managing-cdr-consents) for the full walkthrough. ## Next steps - **Connect a bank** — The general connection flow for every country and provider.' 'Read guide - **Manage CDR consents** — View, renew, and withdraw your data sharing consents.' 'Read guide - **Reconnect a bank** — Renew a lapsed CDR consent or re-authenticate.' 'Read guide ## Related guides - [Managing your CDR consents and data sharing](/docs/connecting-banks/managing-cdr-consents): view, renew, and withdraw consents, and understand what happens to shared data. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): renew a lapsed CDR consent, including re-selecting your accounts. - [Creating your first feed](/docs/bank-feeds/creating-first-feed): sync the connected bank's transactions and balances. - [Scheduling feeds](/docs/bank-feeds/scheduling-feeds): pick a sync time that suits the roughly daily CDR refresh. - [Managing feeds](/docs/bank-feeds/managing-feeds): run syncs on demand and keep connections healthy. --- # Connecting UK banks > Connect United Kingdom bank accounts through Salt Edge and the UK Open Banking consent flow, including the 90-day consent cycle. > Source: https://banksync.io/docs/connecting-banks/uk-banks UK banks connect to BankSync through Salt Edge, an FCA-authorised Account Information Service Provider (AISP), using the UK Open Banking framework. You search for your bank, review a short disclosure of what will be shared, and approve read-only access on your bank's own pages. This guide covers the UK-specific parts of the flow on top of the general [Connect a bank](/docs/connecting-banks/connect-a-bank) steps. [![Connecting a UK or European bank: searching for a supported institution, reviewing the Salt Edge open-banking disclosure, approving on the bank page, and returning to a connected bank card.](https://cdn.banksync.io/videos/connect-open-banking-eu-uk.poster.e3a211520a190ea7.png)](https://cdn.banksync.io/videos/connect-open-banking-eu-uk.6339d85a97715103.mp4) [Watch: Connecting a UK or European bank: searching for a supported institution, reviewing the Salt Edge open-banking disclosure, approving on the bank page, and returning to a connected bank card.](https://cdn.banksync.io/videos/connect-open-banking-eu-uk.6339d85a97715103.mp4) > **Before you start:** You need a BankSync account and your online banking login for the UK institution you want to connect (plus whatever verification your bank uses, such as an app approval or SMS code). The sign-in happens on your bank's own pages, so make sure you can log in to your bank directly first. > **Open Banking keeps you in control:** Access is read-only, scoped to the accounts you approve, and revocable at any time. You sign in on your bank's own consent screen; your credentials never pass through BankSync, and BankSync cannot move money. ## Search for your UK bank Type your bank's name and BankSync searches every supported provider and region at once, then routes UK institutions through Salt Edge automatically. **Find your institution** 1. **Open the Banks page** — Select Banks from the navigation, then click the dashed "Connect a new bank" tile. The "Connect Bank" dialog opens with a search box. 2. **Type your bank name** — Enter at least 2 characters (for example "Barclays", "Monzo", or "HSBC"). Matching institutions appear as cards as you type. 3. **(Optional) narrow the results** — Click the filter button next to the search box and set Country to "United Kingdom" to show only UK institutions. 4. **Check the result card carefully** — Personal and business banking are often separate institutions (for example "HSBC" and "HSBC Business"). Pick the entity that actually holds your accounts. 5. **Select your institution** — Click the matching card. BankSync shows a short disclosure of what data will be accessed and for how long, then opens your bank's secure consent page. ## Approve access at your bank After the disclosure, your bank's own Open Banking consent flow opens in a secure window. The exact screens are controlled by your bank. **Authorise data sharing** 1. **Review what is being requested** — The consent covers account details, balances, and transactions for the accounts you choose. It is read-only. 2. **Sign in to your bank** — Use your normal online banking login and complete your bank's verification step (often an approval in the bank's mobile app). 3. **Select which accounts to share** — Choose only the accounts you want BankSync to access. 4. **Confirm and return** — Approve the consent. The window closes and returns you to BankSync, which fetches your accounts. ### What data UK banks share | Data type | Shared | Notes | | --------------- | ------------------------------------- | ---------------------------------------------------------------- | | Account details | Yes | Account name, type, and identifiers for the accounts you select. | | Balances | Yes | Current and available balance. | | Transactions | Yes | Posted transactions within the history window the bank exposes. | | Account types | Current, savings, and credit accounts | Where the bank exposes them through Open Banking. | ## The 90-day consent cycle UK Open Banking consents typically need reconfirming on a rolling cycle, most commonly every 90 days, with the exact window set by your bank. BankSync shows the expiry date on the bank's detail view and displays a renewal prompt during the final week, so syncs never silently stop. > **Renewing takes about a minute:** 'Renewal is a quick re-authentication with your bank: open the bank in BankSync, click "Renew now" (or "Reconnect"), and approve on your bank\\'s page. Your synced history and feeds are untouched.' ## Confirm it worked You have connected your UK bank successfully when: - The institution appears as a card on the Banks page. - The accounts you approved are linked to that bank. - The bank shows an active state, not a "Requires re-authentication" label. With the bank connected, create a feed to sync its transactions and balances. See [Create your first feed](/docs/bank-feeds/creating-first-feed). ## Troubleshooting > **Common UK-bank issues:** Consent expired or syncs stopped: UK consents lapse on the bank's reconfirmation cycle; renew from the bank's card in BankSync. Wrong entity connected: personal and business banking are separate institutions; connect the one holding your accounts. Bank not found: check the spelling, or search by the bank's parent brand. Connection failed: confirm you can sign in to your bank directly, then retry from the Banks page. ## Next steps - **Connect a bank** — The general connection flow for every country and provider.' 'Read guide - **Manage PSD2 consents** — Track expiry dates and renew or revoke access.' 'Read guide - **Reconnect a bank** — Renew a lapsed consent or re-authenticate.' 'Read guide ## Related guides - [Managing your open banking consents](/docs/connecting-banks/managing-psd2-consents): expiry tracking, renewal, and revocation for UK and European connections. - [Connecting European banks](/docs/connecting-banks/european-banks): the PSD2 flow for banks across the EEA. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): the full renewal flow. - [Creating your first feed](/docs/bank-feeds/creating-first-feed): sync the connected bank's transactions and balances. --- # Connecting European banks > Connect bank accounts across 30 EEA countries through Salt Edge and the PSD2 open banking consent flow, including 180-day consents and SCA. > Source: https://banksync.io/docs/connecting-banks/european-banks European banks connect to BankSync through Salt Edge, a licensed Account Information Service Provider (AISP), under PSD2, the EU's open banking framework. Coverage spans the full EEA: all 27 EU countries plus Norway, Iceland, and Liechtenstein. You search for your bank, review a short disclosure, and approve read-only access on your bank's own pages with Strong Customer Authentication (SCA). This guide covers the Europe-specific parts of the flow on top of the general [Connect a bank](/docs/connecting-banks/connect-a-bank) steps. [![Connecting a UK or European bank: searching for a supported institution, reviewing the Salt Edge open-banking disclosure, approving on the bank page, and returning to a connected bank card.](https://cdn.banksync.io/videos/connect-open-banking-eu-uk.poster.e3a211520a190ea7.png)](https://cdn.banksync.io/videos/connect-open-banking-eu-uk.6339d85a97715103.mp4) [Watch: Connecting a UK or European bank: searching for a supported institution, reviewing the Salt Edge open-banking disclosure, approving on the bank page, and returning to a connected bank card.](https://cdn.banksync.io/videos/connect-open-banking-eu-uk.6339d85a97715103.mp4) > **Before you start:** You need a BankSync account and your online banking login for the European institution you want to connect. SCA means your bank will ask for two verification factors (for example app approval plus a code), so have your bank's mobile app or token generator handy. > **PSD2 keeps you in control:** Access is read-only, scoped to the accounts you approve, and revocable at any time. You authenticate on your bank's own pages under SCA; your credentials never pass through BankSync, and BankSync cannot move money. ## Search for your European bank Type your bank's name and BankSync searches every supported provider and region at once, then routes European institutions through Salt Edge automatically. The country filter defaults to your locale when it matches a supported country. **Find your institution** 1. **Open the Banks page** — Select Banks from the navigation, then click the dashed "Connect a new bank" tile. 2. **Type your bank name** — Enter at least 2 characters (for example "N26", "Deutsche Bank", "BNP Paribas", or "ING"). Matching institutions appear as cards as you type. 3. **(Optional) narrow by country** — Click the filter button and pick your country. This matters for pan-European brands: "ING" in the Netherlands and "ING" in Poland are separate institutions with separate consents. 4. **Check the result card carefully** — Branded banking groups can list many member banks (for example hundreds of local Sparkasse and Volksbank institutions in Germany). Pick the exact institution you bank with. 5. **Select your institution** — Click the matching card. BankSync shows a short disclosure of what will be accessed and for how long, then opens your bank's secure consent page. ## Approve access at your bank **Authorise data sharing** 1. **Review what is being requested** — The consent covers account details, balances, and transactions. It is read-only under PSD2. 2. **Complete Strong Customer Authentication** — Sign in with your bank credentials and confirm with your second factor (app approval, code generator, or SMS). 3. **Select which accounts to share** — Choose only the accounts you want BankSync to access. 4. **Confirm and return** — Approve the consent. The window closes and returns you to BankSync, which fetches your accounts. ### What data European banks share | Data type | Shared | Notes | | --------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Account details | Yes | Account name, type, IBAN or identifiers for the accounts you select. | | Balances | Yes | Current and available balance. | | Transactions | Yes | Posted transactions within the history window the bank exposes (commonly 90 days to 2 years, set per bank). | | Account types | Current, savings, and card accounts | Where the bank exposes them under PSD2. | > **History windows vary by bank:** 'Each bank decides how much transaction history its PSD2 API exposes. Many banks provide around 90 days on the first connection; some provide years. BankSync syncs everything the bank makes available. For older records, export a statement from your online banking.' ## Consents of up to 180 days Consent duration is set per bank. Since the 2023 update to the European SCA standards, most EEA banks issue consents lasting up to 180 days before a re-authentication is required. BankSync shows the expiry date on each bank's detail view and displays a renewal prompt during the final week. > **Renewing takes about a minute:** 'Open the bank in BankSync, click "Renew now" (or "Reconnect"), and complete SCA on your bank\\'s page. Your synced history and feeds are untouched.' ## Confirm it worked You have connected your European bank successfully when: - The institution appears as a card on the Banks page. - The accounts you approved are linked to that bank. - The bank shows an active state, not a "Requires re-authentication" label. With the bank connected, create a feed to sync its transactions and balances. See [Create your first feed](/docs/bank-feeds/creating-first-feed). ## Troubleshooting > **Common European-bank issues:** 'Consent expired or syncs stopped: PSD2 consents lapse at the end of their window; renew from the bank\\'s card in BankSync. Wrong country selected: pan-European brands are separate institutions per country; connect the one for the country where you hold the account. SCA loop or failure: complete the verification in your bank\\'s mobile app first, then retry. Bank not found: try the local-language name (for example "Caixa Geral" rather than a translation).' ## Next steps - **Connect a bank** — The general connection flow for every country and provider.' 'Read guide - **Manage PSD2 consents** — Track expiry dates and renew or revoke access.' 'Read guide - **Reconnect a bank** — Renew a lapsed consent or re-authenticate.' 'Read guide ## Related guides - [Managing your open banking consents](/docs/connecting-banks/managing-psd2-consents): expiry tracking, renewal, and revocation. - [Connecting UK banks](/docs/connecting-banks/uk-banks): the UK Open Banking flow and its 90-day cycle. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): the full renewal flow. - [Creating your first feed](/docs/bank-feeds/creating-first-feed): sync the connected bank's transactions and balances. --- # Connecting brokerages > Connect brokerage and investment accounts through SnapTrade to sync holdings, trades, and balances. > Source: https://banksync.io/docs/connecting-banks/brokerages Brokerages and investment accounts connect to BankSync through SnapTrade, a provider built specifically for investment data. You search for your brokerage, sign in through SnapTrade's secure window, and BankSync then has access to your positions, trades, balances (including settled cash), and account details, ready to power a holdings or trades feed. [![Connecting a brokerage account: searching for Charles Schwab, authorizing through SnapTrade, confirming the provider result, and returning to a connected investment account card.](https://cdn.banksync.io/videos/connect-brokerage.poster.9fca346cc66af0d9.png)](https://cdn.banksync.io/videos/connect-brokerage.4d68e730ad07118d.mp4) [Watch: Connecting a brokerage account: searching for Charles Schwab, authorizing through SnapTrade, confirming the provider result, and returning to a connected investment account card.](https://cdn.banksync.io/videos/connect-brokerage.4d68e730ad07118d.mp4) > **Your credentials stay with your brokerage:** BankSync connects to brokerages through SnapTrade. You enter your brokerage login in SnapTrade's own secure window, not in BankSync. BankSync never sees or stores your brokerage password. > **Before you start:** You need a BankSync account and your brokerage login (username and password, plus any two-factor method your broker uses such as an SMS or authenticator code). Confirm you can sign in to your brokerage's own website or app first. ## Open Banks and search for your brokerage Brokerages live alongside your banks. You search the same way, and BankSync routes investment institutions through SnapTrade automatically. **Find your brokerage** 1. **Go to the Banks page** — Open BankSync and select Banks from the navigation. This is where every connected institution, including brokerages, appears. 2. **Click 'Connect a new bank'** — Select the dashed "Connect a new bank" tile. The "Connect Bank" dialog opens with the subtitle "Search and connect your financial institution". 3. **Type your brokerage name** — In the "Search institutions" box, enter at least 2 characters (for example "Schwab", "Fidelity", "Robinhood", or "Questrade"). Matching institutions appear as cards as you type. 4. **(Optional) filter to SnapTrade** — Click the filter button next to the search box to open Filters, then under Provider tap "SnapTrade" to show only brokerage results. The provider chips are All, Plaid, SnapTrade, SaltEdge, and Fiskil. 5. **Confirm the result is a brokerage** — A brokerage card shows an "Investment" account-type tag (the chart icon) and "SnapTrade" as its provider. Click the card to start the connection. ![The BankSync Connect Bank dialog searching for Schwab, showing brokerage result cards (Charles Schwab, Fidelity, Robinhood, Questrade), each with an Investment account-type tag and the SnapTrade provider.](https://cdn.banksync.io/screenshots/banks/connect-search-brokerage.f87f5fe68a9fcfdb.png "Searching for a brokerage in the Connect Bank dialog, connected through SnapTrade.") > **Brokerages skip the region step:** Brokerages are global on SnapTrade and aren't tied to a country, so there is no separate region selection. When you click a brokerage card, BankSync goes straight to the SnapTrade login window. ## Sign in through SnapTrade After you select a brokerage, SnapTrade's secure connection window opens. Because you already chose the institution in BankSync, SnapTrade takes you straight to that broker's sign-in. **Authorize the connection** 1. **Sign in to your broker** — Enter your brokerage credentials in the SnapTrade window. This is your broker's own login, handled by SnapTrade. 2. **Complete verification** — Approve any two-factor prompt your broker requires, such as an SMS code, email code, or an authenticator approval. 3. **Grant read access** — Confirm the read-only data permission so SnapTrade can share your positions, balances, and activity with BankSync. 4. **Return to BankSync** — When the window finishes, BankSync confirms the connection and the brokerage appears as a card on your Banks page. If you already have a connection to the same brokerage, BankSync shows an "Existing Connections" screen. Choose "Reconnect" to refresh the existing connection rather than opening a fresh login. ## What investment data you get Once connected, BankSync reads four kinds of investment data from the brokerage. Each one maps to a feed type you can sync to your spreadsheet, database, or other integration. | Data | What it contains | Feed type | | -------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------- | | Holdings (positions) | Every security you hold: symbol, security name, quantity, current price, market value, cost basis, and unrealized gain/loss | Holdings | | Trades (activity) | Buys, sells, dividends, transfers, and other account activity, with date, symbol, quantity, price, total, and fees | Trades | | Balances | Account-level totals including settled cash | Holdings / balances | | Account details | Each investment account on the connection and its account type | All investment feeds | > **Settled cash appears in your holdings:** Settled cash held in a brokerage account is surfaced as a cash position alongside your securities, priced at 1 per unit in the account's currency. That means a holdings feed shows both your invested positions and your uninvested cash in one place. ## Real-time vs cached data How fresh your investment data is depends on the broker. For supported brokerages, BankSync reads live positions and balances at sync time. For others, data reflects the broker's most recent snapshot rather than a tick-by-tick view. Either way, BankSync delivers the latest data the broker makes available when the feed runs. > **A degraded connection can serve stale data:** If the broker-side connection becomes degraded (for example the broker's session has expired or the provider can't reach it), SnapTrade may keep returning the last successful snapshot. The bank can still look healthy while the numbers stop moving. When figures stop updating, reconnect the brokerage to re-authorize the session and pull fresh data. ## Confirm it worked You have connected your brokerage successfully when: - The brokerage appears as a card on the Banks page (no longer just the "Connect a new bank" tile). - Opening the brokerage shows its investment accounts and their account types. - Your holdings (positions) and balances appear, including any settled cash as a cash position. - The connection shows an active state rather than a "Requires re-authentication" label. If holdings and balances are populated, you are ready to build a feed. ## Troubleshooting > **Common issues:** 'Stale or unchanging data: the broker-side connection is likely degraded. Open the brokerage and use "Reconnect / Add Accounts" (or "Reconnect Now") to re-authorize, then run a sync. Brokerage not listed: try the broker\\'s full or parent-company name; if it still doesn\\'t appear, use the "Request this bank" prompt that shows when few results come back. No holdings or only cash: confirm the account actually holds positions and that you granted read access during the SnapTrade login; some account types share balances but few positions. Requires re-authentication: the broker\\'s session expired, so open the brokerage and reconnect to refresh consent.' ## Next steps With your brokerage connected, set up feeds to sync its investment data on a schedule. - **Sync holdings** — Track current positions, values, and settled cash. - **Sync trades** — Capture buys, sells, dividends, and other activity. [Sync holdings](/docs/bank-feeds/sync-holdings) ## Related guides - [How to sync holdings](/docs/bank-feeds/sync-holdings): track positions, values, and settled cash in a feed. - [How to sync trades](/docs/bank-feeds/sync-trades): capture buys, sells, dividends, and other activity. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): refresh a stale or degraded brokerage session without losing history. - [Connect a bank](/docs/connecting-banks/connect-a-bank): the equivalent flow for everyday bank accounts. --- # Managing your CDR consents and data sharing > View, renew, and withdraw the Consumer Data Right (CDR) consents behind your Australian bank connections, and understand what happens to data you share. > Source: https://banksync.io/docs/connecting-banks/managing-cdr-consents When you connect an Australian bank, you do it through the Consumer Data Right (CDR), Australia's regulated open banking framework. BankSync acts as a CDR representative of Fiskil Pty Ltd, an Accredited Data Recipient (ADRBNK000246). This guide explains how to see and manage the consents behind your Australian connections, and what happens to data once you share it with a destination. > **Australian connections only:** This guide applies to banks connected via the CDR (Australian institutions through Fiskil). US, Canadian, UK, and EU connections use different frameworks and don't appear in the Data sharing dashboard. ## Before you connect: what you're agreeing to Before the Fiskil consent window opens, BankSync shows a short summary of what you're about to share, why, and for how long. It confirms that: - BankSync accesses account details, balances, and transactions for the accounts you choose at your bank. - The data is used only to sync to the destinations you set up. - Your consent lasts up to 12 months, and you can withdraw it at any time. You then complete the actual consent in your bank's own secure CDR window, never in BankSync. See [Connecting Australian banks](/docs/connecting-banks/australian-banks) for the full connection walkthrough. ![The pre-consent screen for connecting an Australian bank, explaining what data BankSync accesses, why, the 12-month consent duration, and the CDR representative relationship with Fiskil, with Continue to consent and Cancel buttons.](https://cdn.banksync.io/screenshots/banks/cdr-preconsent.77e57cc947c2e070.png) ## The Data sharing dashboard Once you have at least one Australian bank connected, a **Data sharing** tab appears in **Settings**. It lists every CDR consent for the workspace, including past ones, and for each shows: - **Status**: active, expired, or withdrawn. - **What you're sharing**: the data types the consent covers (for example account details, balances, transactions) and the accounts it applies to. - **Given on** and **Expires**: when you granted the consent and when it ends. - **Where it goes**: the feeds currently routing this bank's data, and their destinations. ![The Data sharing settings panel listing CDR consents grouped by institution, each showing status, the data types and accounts shared, the dates given and expiring, the feeds the data flows to, and a Stop sharing action.](https://cdn.banksync.io/screenshots/settings/data-sharing.66a022c751c20d76.png) > **This is your consent record:** The Data sharing dashboard is the consumer dashboard required under the CDR rules. You can also view and manage consents at Fiskil's hosted dashboard (consents.fiskil.app), linked from each consent. ## Sending CDR data to a destination When you set up a feed from an Australian bank to a destination such as Google Sheets, Notion, Airtable, or Excel, BankSync asks you to confirm a disclosure before any data flows. This is required because the data is leaving the CDR-protected environment. The confirmation states, in plain terms: - Data sent to the destination **will not be regulated as part of the Consumer Data Right** once delivered. - It will instead be handled under applicable privacy law, including the **Privacy Act 1988 (Cth)**, and the destination's own privacy policy. - You should review how that destination handles your data before continuing. ![The data sharing disclosure dialog shown before sending CDR data to Notion, stating the data will not be regulated as part of the Consumer Data Right, will be governed by the Privacy Act 1988 and Notion's privacy policy, with a link to review it and an I understand, send my data button.](https://cdn.banksync.io/screenshots/feeds/cdr-disclosure.2b686bf8ec2f9d93.png) > **Once data leaves, CDR protections no longer apply:** After BankSync delivers data to your Notion workspace, spreadsheet, or database, that copy is governed by the receiving service's terms and the Privacy Act, not by the CDR. Review the destination's privacy policy, and remember that withdrawing your bank consent later does not pull back data already delivered. You confirm this once per feed, and again whenever you change the feed's destination (a new destination is a new recipient). For a destination you operate yourself, such as your own database, you also confirm that you control it and can access the data delivered to it. ## Renewing an expiring consent CDR consents are time-limited. As a consent nears its expiry, BankSync shows a reminder on the bank and in the Data sharing dashboard. When a consent lapses, the bank's data stops refreshing until you reconnect. A consent within 30 days of expiry shows an "expires in N days" badge. Use Reconnect to start a fresh CDR consent in your bank's window. Reconnecting creates a new consent and replaces the previous one. ![The Data sharing section on a bank's detail view, showing the CDR consent status and expiry date, the data types being shared as chips, and Stop sharing and Manage data sharing actions.](https://cdn.banksync.io/screenshots/banks/consent-section.3e7999dd2bf333ab.png) See [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank) for the full re-authorisation flow. ## Withdrawing a consent You can stop sharing at any time. Withdrawal takes effect immediately. **Stop sharing a bank's data** 1. **Open Settings → Data sharing** — Find the consent for the bank you want to stop sharing. 2. **Choose Stop sharing** — Confirm in the dialog. BankSync revokes the consent with your bank straight away. 3. **What happens next** — BankSync stops collecting data from that bank immediately, and feeds that rely only on it are paused. Data already delivered to your destinations stays where you sent it. You can reconnect at any time. > **What BankSync holds, and destroys:** 'BankSync does not store your transactions or balances at rest, reads are live. When you withdraw or a consent expires, BankSync also clears the small amount of working data tied to that bank and pauses dependent feeds. Your bank and Fiskil destroy their copies per the CDR rules.' You can also withdraw directly from your bank, or from Fiskil's consent dashboard. Any of these takes effect across the chain. ## Records and complaints You can request further records of how your CDR data has been handled (CDR Rule 9.5) by contacting . For complaints and dispute-resolution options, see the BankSync CDR policy linked from the Data sharing dashboard. The Office of the Australian Information Commissioner (OAIC) is the CDR complaints authority. ## A note on AI assistants (MCP) CDR-connected bank data is **not** currently available through BankSync's MCP server or AI assistants such as ChatGPT and Claude, while our accreditation partner reviews AI access to CDR data. You can still route your CDR data to a destination you control (a spreadsheet, Notion, Airtable, or your own database) and analyse it there. ## Related guides - [Connecting Australian banks](/docs/connecting-banks/australian-banks): the full CDR connection walkthrough. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): renew a lapsed CDR consent. - [Creating your first feed](/docs/bank-feeds/creating-first-feed): send your bank data to a destination. --- # Managing your open banking consents (UK and Europe) > How PSD2 and UK Open Banking consents work in BankSync: tracking expiry dates, renewing before they lapse, and revoking access. > Source: https://banksync.io/docs/connecting-banks/managing-psd2-consents UK and European bank connections run on time-limited open banking consents: up to 180 days for most EEA banks under PSD2, and typically a 90-day reconfirmation cycle for UK banks. This guide explains how BankSync tracks those consents, how renewal works, and how to revoke access. [![Connecting a UK or European bank: searching for a supported institution, reviewing the Salt Edge open-banking disclosure, approving on the bank page, and returning to a connected bank card.](https://cdn.banksync.io/videos/connect-open-banking-eu-uk.poster.e3a211520a190ea7.png)](https://cdn.banksync.io/videos/connect-open-banking-eu-uk.6339d85a97715103.mp4) [Watch: Connecting a UK or European bank: searching for a supported institution, reviewing the Salt Edge open-banking disclosure, approving on the bank page, and returning to a connected bank card.](https://cdn.banksync.io/videos/connect-open-banking-eu-uk.6339d85a97715103.mp4) > **What a consent covers:** A consent is your authorisation for Salt Edge (a licensed AISP) to read specific data from a specific bank on BankSync's behalf: account details, balances, and transactions for the accounts you approved. It is read-only, and it cannot be used to move money. ## Where to see a consent's status Open any UK or European bank from the Banks page. The bank's detail view shows: - **Consent expiry date**: when the current consent lapses. - **Renewal prompt**: during the final week before expiry, an amber "consent expires in N days" card appears with a "Renew now" button. - **Requires re-authentication**: shown after a consent has expired or been revoked, alongside a Reconnect button. ## Renewing before expiry Renewal is a fresh authorisation with your bank and takes about a minute. **Renew a consent** 1. **Open the bank** — From the Banks page, open the UK or European bank showing the renewal prompt. 2. **Click Renew now** — BankSync shows the disclosure of what will be accessed, then opens your bank's consent page. 3. **Approve at your bank** — Sign in and complete your bank's verification (SCA in the EEA, app approval or similar in the UK). Re-select the accounts you want to keep sharing. 4. **Done** — The new consent replaces the old one and the expiry date updates. Your synced history and feeds are untouched. > **Re-select every account you still want:** 'Renewal is a re-consent at the bank. Accounts you leave unticked drop out of the new consent and stop syncing, even if they were shared before.' ## What happens when a consent lapses If a consent expires without renewal: - The bank's card shows "Requires re-authentication". - Scheduled syncs for that bank stop returning new data (already-synced data is untouched). - Reconnecting issues a fresh consent and syncs resume from where they left off. ## Revoking access You can end data sharing at any time, from either side: - **In BankSync**: disconnect the bank from its detail view. BankSync revokes the consent with the bank through Salt Edge as part of the disconnect. - **At your bank**: most banks list active data-sharing permissions in their online banking (often under "Open Banking", "Data sharing", or "Third-party access") and let you revoke there. BankSync detects the revocation and marks the connection as requiring re-authentication. > **Data already synced to your destinations:** 'Revoking a consent stops future access. Data already delivered to your spreadsheet, database, or other destinations stays there under your control; delete it from the destination if you no longer want it.' ## Related guides - [Connecting UK banks](/docs/connecting-banks/uk-banks): the UK flow and its 90-day cycle. - [Connecting European banks](/docs/connecting-banks/european-banks): the PSD2 flow across the EEA. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): the full renewal flow, step by step. - [Removing a bank](/docs/connecting-banks/removing-a-bank): disconnecting and what happens to your data. --- # Reconnecting a bank > Reauthenticate a bank whose connection has expired or errored so data syncs again, without losing history. > Source: https://banksync.io/docs/connecting-banks/reconnecting-a-bank When a bank connection stops working, BankSync flags it as needing attention and you fix it by reconnecting. Reconnecting reopens your provider's secure window so you can re-enter your login or re-confirm consent, which refreshes the connection and resumes syncing without losing any of the history already pulled in. > **Reconnecting never erases your history:** 'Re-authentication refreshes the connection in place. Your already-synced transactions, balances, holdings, and the accounts you previously selected all stay exactly as they are. Reconnecting only restores fresh access so new data can flow again.' > **Before you start:** 'You need Editor access to the workspace (viewers see a "View only" notice and cannot reconnect), and your online banking login plus any two-factor method your bank uses (such as an SMS or email code). If the bank is owned by a client portal, only the client can reconnect it from their own Banks tab.' [![Reconnecting an expired bank in the BankSync app: the Banks page with a Chase card showing Reconnection needed, clicking Reconnect, reauthorizing through Plaid's secure window, and the card returning to healthy and syncing.](https://cdn.banksync.io/videos/reconnect-a-bank.poster.204bccccc185660a.png)](https://cdn.banksync.io/videos/reconnect-a-bank.fa0e69267315e642.mp4) [Watch: Reconnecting an expired bank in the BankSync app: the Banks page with a Chase card showing Reconnection needed, clicking Reconnect, reauthorizing through Plaid's secure window, and the card returning to healthy and syncing.](https://cdn.banksync.io/videos/reconnect-a-bank.fa0e69267315e642.mp4) ## Spot a bank that needs attention A healthy bank shows its connection date (for example "Connected: 1/14/2026"). A bank that needs re-authentication is clearly flagged on its card on the Banks page. **Find the flagged bank** 1. **Open the Banks page** — Select Banks from the navigation. Every connected institution appears as a card. 2. **Look for the amber 'Reconnection needed' label** — A bank that needs attention shows an amber warning triangle with the text "Reconnection needed" in its card body, and a "Reconnect" button appears in the bottom-left of the card. BankSync classifies why a connection broke and surfaces the appropriate action. The common states are: | State on the connection | What it means | What to do | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | Requires re-authentication | Credentials or consent need refreshing (expired consent, changed password, revoked access, or a broken provider session). This is the most common, user-fixable state. | Reconnect (re-enter your login or re-confirm consent) | | Awaiting your action | The provider paused mid-flow and needs a response, such as a multi-factor challenge or a consent confirmation. | Reconnect and complete the prompt the provider shows | | Provider temporarily unavailable | The bank or provider is degraded or in an outage. This is not your fault and the scheduler backs off automatically. | Wait and retry later; reconnect only if the flag persists | > **What triggers a reconnect:** 'Connections drop into a "requires re-authentication" state for everyday reasons: you changed your online banking password, your bank tightened security, an Open Banking / CDR consent reached its expiry, a provider login session expired after a period of inactivity, or a brokerage feed went stale or degraded. BankSync\\'s banner explains it as: "This can happen when banks update security requirements or after a period of inactivity."' ![A bank card for Chase showing an amber Reconnection needed row and a Reconnect button in the card footer.](https://cdn.banksync.io/screenshots/banks/reconnect-needed.02e9ee7e2828ee21.png "A bank that needs re-authentication shows an amber Reconnection needed state on its card.") ## Reconnect the bank You can start the reconnect straight from the card, or open the bank to see the full re-authentication banner first. Both run the same flow: BankSync reopens your provider's secure window in update mode so you can refresh access. **Re-authenticate the connection** 1. **Click 'Reconnect' on the card** — On the Banks page, click the "Reconnect" button on the flagged bank's card. Alternatively, click the card to open it. 2. **(If you opened the bank) review the banner and click 'Reconnect Now'** — The bank's edit panel shows an amber banner titled "Bank Connection Requires Re-authentication" with the message "Your bank requires you to verify your login credentials." Click the "Reconnect Now" button. You can also use the "Reconnect / Add Accounts" button at the bottom of the accounts list. 3. **Sign in or re-confirm consent in the provider window** — The provider's own secure window opens. Re-enter your online banking credentials and complete any verification step (such as an SMS or email code), or re-confirm your data-sharing consent. You enter everything in the provider's window, not in BankSync. 4. **Keep your existing account selection** — Because reconnecting runs in update mode, your previously shared accounts are preserved. If the provider shows the account picker, leave your existing accounts selected (you can also tick additional accounts here if you want to add more). 5. **Finish and return to BankSync** — When the provider window completes, it closes and returns you to BankSync. The connection is refreshed and a fresh sync begins. > **Reconnecting from an existing-connection screen:** 'If you start a brand-new connection to a bank you already have, BankSync shows the "Existing Connections" screen. A connection that needs attention is marked "Requires re-authentication" there, with a "Reconnect" button. Connections that are healthy show "Add Accounts" instead. Picking "Reconnect" runs the same re-authentication flow described above.' ## Per-provider notes The reconnect button is the same everywhere, but the window it opens differs by provider. - **Plaid (US and Canada)** — When Plaid reports the connection needs a login, the bank shows "Reconnection needed". Reconnect reopens Plaid's window in update mode so you re-enter your credentials and any MFA. Your existing account selection is preserved, and the account picker is available if you want to add accounts at the same time. - **Fiskil (Australia, CDR)** — A CDR consent has a fixed lifetime and lapses on expiry. Reconnect re-runs the CDR consent flow at your bank, granting a fresh consent. Because it is a re-consent, the bank asks you to select accounts again: tick every account you still want to share so it carries over. - **SnapTrade (brokerages)** — A brokerage connection can go stale or degraded provider-side, where the last cached snapshot keeps being served but stops updating. Reconnect re-authorizes the brokerage session so live positions and balances refresh again. - **Mid-flow prompts** — Some banks pause mid-flow for a multi-factor or consent confirmation ("Awaiting your action"). Reconnect resumes that flow so you can complete the prompt and restore access. > **Brokerage feeds can look healthy while stale:** A degraded brokerage connection may not show a hard error, yet its data stops refreshing. If a brokerage account's balances or holdings look frozen even though no error is flagged, reconnecting it forces a fresh authorization and a new pull. Reconnecting roughly every other day for the same brokerage is a sign the provider-side connection is degraded, which the team can escalate. ## Confirm it worked You have reconnected successfully when: - The amber "Reconnection needed" label is gone from the bank's card on the Banks page. - The card again shows the normal connected state instead of the re-authentication banner. - The accounts you had selected are still attached to the bank, with their existing history intact. - A fresh sync runs and new data starts appearing in any feeds reading from that bank. > **Force an immediate sync:** 'Reconnecting kicks off a refresh, but if you want new data right away you can trigger a sync from the feed that reads this bank. See "Managing feeds" for how to run a sync on demand and check the run log.' ## Troubleshooting > **If reconnecting doesn't stick:** 'Provider window won\\'t open: confirm pop-ups aren\\'t blocked, then click Reconnect again. Still flagged after reconnecting: verify you can sign in directly on your bank\\'s own website, then reconnect and complete every verification step the provider asks for. Accounts missing after reconnect: open the bank and use "Reconnect / Add Accounts" to reopen the account picker and re-select them. Flag returns within a day or two (brokerage): the provider-side connection is likely degraded, not a credential problem; reconnect restores it temporarily and the team can escalate to the provider. Portal-owned bank: you\\'ll see "Managed by the client" and a "Copy portal link" button. Only the client can reconnect, so send them the portal link so they can reconnect from their Banks tab. Provider unavailable: if the bank shows a temporary provider issue, wait and let the scheduler retry rather than reconnecting repeatedly.' [Manage your feeds](/docs/bank-feeds/managing-feeds) ## Related guides - [Managing your open banking consents (UK and Europe)](/docs/connecting-banks/managing-psd2-consents): renewal for time-limited PSD2 and UK Open Banking consents. - [Connect a bank](/docs/connecting-banks/connect-a-bank): how connections are first established for every provider. - [Managing feeds](/docs/bank-feeds/managing-feeds): run syncs on demand and check the run log after reconnecting. - [Removing a bank](/docs/connecting-banks/removing-a-bank): disconnect an institution you no longer want to keep reconnecting. - [Client portals](/docs/client-portals/setup): how reconnection works for client-managed banks. --- # Removing a bank > Remove or disconnect a bank, what happens to its feeds and provider credentials, and how to reactivate within the grace window. > Source: https://banksync.io/docs/connecting-banks/removing-a-bank Removing a bank disconnects an institution from your workspace and stops it from powering any feeds. BankSync does this as a soft delete first: the bank is marked for deletion and stays recoverable for a short window before it is removed for good, so an accidental click is easy to undo. > **Before you start:** 'You need an Admin or higher role in the workspace (Viewers cannot disconnect banks). If the bank is still used by any feeds, disconnect is blocked until you remove it from those feeds first. If the bank is managed inside a client portal, only the client can disconnect it from their own Banks tab.' [![Removing a bank safely](https://cdn.banksync.io/videos/remove-a-bank.poster.2b64158bc4352400.png)](https://cdn.banksync.io/videos/remove-a-bank.8fef02f510188c62.mp4) [Watch: Removing a bank safely](https://cdn.banksync.io/videos/remove-a-bank.8fef02f510188c62.mp4) ## Decide: remove the bank, or just pause its feeds? Disconnecting a bank is permanent once the window closes, and it eventually revokes the provider connection. If you only want to stop syncing for a while (for example, you are pausing a client or taking a break), do not remove the bank. Instead, turn off the schedule on its feeds and leave the connection in place. | Goal | Do this | Effect | | ----------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Stop automated syncs temporarily, keep the connection | Open the feed, go to the Schedule tab, turn off "Automatically sync periodically" | Connection stays active, no provider revocation, you can still run manual syncs | | Stop one feed but keep the bank | Delete the feed (see [Managing feeds](/docs/bank-feeds/managing-feeds)) | The bank stays connected and can power other feeds | | Remove the institution entirely | Disconnect the bank (below) | Bank is soft-deleted, then permanently removed and its provider connection is revoked | > **Pausing keeps your data flowing later:** 'A paused or unscheduled feed can be switched back on at any time with no reconnect. A disconnected bank cannot be reconnected to the same institution until after it is permanently removed, so prefer pausing when you are unsure.' ## Disconnect a bank **Remove the connection** 1. **Open the Banks page** — Select Banks from the navigation. Each connected institution appears as a card. 2. **Open the bank** — Click the bank's card to open its detail panel, which lists the bank's accounts. 3. **Click 'Disconnect Bank'** — The "Disconnect Bank" button sits at the bottom of the panel. Clicking it opens a confirmation dialog. 4. **Read the confirmation, then confirm** — The dialog explains that the bank will be marked for deletion and permanently removed at the end of the month, and that you can reactivate it before then. Click "Disconnect" to proceed, or "Cancel" to back out. > **If the bank is still in a feed:** 'When the bank is linked to one or more feeds, the dialog instead says it "is linked to existing syncs and cannot be disconnected until those syncs are removed" and shows a "View Linked Syncs" button. Use it to jump to those feeds, remove the bank from each (or delete the feed), then come back and disconnect.' ## What happens after you disconnect Disconnecting does not delete everything instantly. BankSync soft-deletes the bank so you have a grace period to undo it. - **Grace window** — The bank is marked for deletion and stays in your Banks list (greyed out, with a "Reactivate Bank" option) for about 30 days, until the end-of-month cleanup runs. - **Feeds stop** — Feeds that read from this bank stop receiving its data. Any feed that depends solely on this bank will produce no new rows once the connection is gone. - **Credentials revoked** — On permanent removal, the underlying provider connection is revoked (for example the Plaid connection is removed or the SnapTrade authorization is revoked). For Australian CDR banks you can also withdraw the data-sharing consent yourself at any time from your bank's data-sharing dashboard. While the bank is in this state, its detail panel shows a "Bank Scheduled for Deletion" banner noting the date it was marked for deletion. Data already written to your integrations (spreadsheets, databases, Notion, Airtable) by past syncs is not touched by disconnecting. > **You cannot reconnect the same bank until removal completes:** 'Until the end-of-month cleanup permanently removes a disconnected bank, you cannot reconnect that same institution. If you might still need it, reactivate the existing connection instead of trying to add it again.' ![A disconnected bank card for Wells Fargo shown in a muted soft-deleted state with a Reactivate action available.](https://cdn.banksync.io/screenshots/banks/soft-deleted.385971e84afb82c2.png "A disconnected bank stays reactivatable until the end-of-month cleanup.") ## Reactivate within the window Changed your mind? As long as the bank is still marked for deletion (it is still listed and greyed out), you can restore it with no reconnect. **Undo the disconnect** 1. **Open the bank** — On the Banks page, click the greyed-out card for the bank that is scheduled for deletion. 2. **Click 'Reactivate Bank'** — In the yellow "Bank Scheduled for Deletion" banner, click "Reactivate Bank". The deletion mark is cleared and the bank returns to its active state. 3. **Re-enable your feeds if needed** — Reactivation restores the connection, but any feeds you removed the bank from must be pointed back at it. Check those feeds in the Feeds tab. > **Reactivation counts toward your plan limit:** Bringing a bank back re-adds an active connection, so it is checked against your plan's bank limit (1 on Starter, 5 on Standard, 15 on Professional, 30 on Business, unlimited on Enterprise; the Free plan allows 0 connected banks). If reactivating would push you over your limit, BankSync re-cancels it. Upgrade or remove another bank first. See Plans and billing for limits. ## Confirm it worked You have removed the bank when: - The bank's card shows a "Bank is marked for deletion" or "Bank Scheduled for Deletion" state on the Banks page. - Feeds that read only from this bank no longer produce new data on their next run. - After the end-of-month cleanup, the bank no longer appears in your Banks list at all, and the provider connection has been revoked. You have reactivated the bank when: - The "Bank Scheduled for Deletion" banner is gone and the card is no longer greyed out. - The bank shows an active state and its accounts are visible again in the detail panel. ## Troubleshooting > **Common issues:** '"Cannot be disconnected": the bank is still linked to feeds. Open "View Linked Syncs", remove the bank from each feed (or delete the feed), then disconnect. No "Disconnect Bank" button: you may be a Viewer, or the bank is managed inside a client portal (only the client can disconnect it there). Reactivation rejected: reactivating exceeded your plan\\'s bank limit, so the bank was re-cancelled; upgrade or free up a slot, then reactivate again. Need the bank back but the window has passed: once permanently removed you must connect it fresh from "Connect a new bank" and re-select your accounts.' [Manage your feeds](/docs/bank-feeds/managing-feeds) ## Related guides - [Managing feeds](/docs/bank-feeds/managing-feeds) and [Scheduling feeds](/docs/bank-feeds/scheduling-feeds): stop syncs without removing the bank. - [Reconnecting a bank](/docs/connecting-banks/reconnecting-a-bank): refresh a bank that just needs re-authentication instead of removing it. - [Plans and billing](/docs/account-billing/managing-your-plan): review your bank limit before reactivating. - [Client portals](/docs/client-portals/setup): manage portal-owned bank connections, which only the client can disconnect. --- # Dashboards & Widgets Overview > Build charts, KPIs, and richly formatted tables from your synced bank data on an always-editable canvas, then publish or embed them. > Source: https://banksync.io/docs/dashboards/dashboards-overview Dashboards turn the financial data you already sync with BankSync into charts, big-number KPIs, and richly formatted tables. You build a dashboard by dropping **widgets** onto a grid, pointing each widget at your data, and choosing how to chart it. There is no separate report to build or refresh: a widget always re-reads its source when the dashboard loads, so what you see reflects the latest data BankSync has. [![A tour of BankSync dashboards: the dashboards tree and the populated Cashflow board on the always-editable canvas, close-ups of the KPI tiles, the income-vs-spending chart, the category donut and the formatted transactions table, then adding a KPI widget from the widget library, which lands on the canvas and autosaves.](https://cdn.banksync.io/videos/dashboards-overview.poster.9dec43d3cf11a049.png)](https://cdn.banksync.io/videos/dashboards-overview.4bf1988e677f9209.mp4) [Watch: A tour of BankSync dashboards: the dashboards tree and the populated Cashflow board on the always-editable canvas, close-ups of the KPI tiles, the income-vs-spending chart, the category donut and the formatted transactions table, then adding a KPI widget from the widget library, which lands on the canvas and autosaves.](https://cdn.banksync.io/videos/dashboards-overview.4bf1988e677f9209.mp4) Most widgets read from a **feed** (the data your feeds keep synced to your connected tools, like a sheet or warehouse). A widget can also read straight from a connected **bank or provider** for the freshest possible numbers, from a small **static table** you type in yourself (handy for targets or reference lists), or from **two or more feeds combined**. Feeds are the common starting point, but they are not the only option. > **Feed data vs. live bank data:** 'A feed-backed widget reads the copy your feed last synced to your connected tool, so it is as fresh as your most recent sync (typically hourly or daily). A bank/provider source reads the bank directly each time, so it is the most up-to-the-moment, at the cost of a slower load. Pick a feed for everyday dashboards; reach for a live bank source when you need the very latest balance or transaction.' ![A data preview table with richly formatted columns: signed currency amounts, a Posted/Pending/Cleared status column, a budget-used percentage bar, and a 4-week trend sparkline.](https://cdn.banksync.io/screenshots/dashboards/data-preview.2083d5619b34503f.png "Tables can render currency, status pills, progress, and sparklines, so a table reads as clearly as a chart.") > **Prerequisites:** Dashboards visualize data you have already synced, so before you start make sure you have > connected a bank and created at least one feed (so there is data to chart). New here? See > Connecting a bank and Create your first > feed. > **Availability:** 'Dashboards are in beta and roll out per workspace. If you do not see Dashboards in your left navigation yet, it is not enabled for your workspace.' ## What a dashboard is made of A dashboard has four moving parts. You will spend most of your time in the **canvas** (where widgets sit) and the **inspector** (the panel that configures whichever widget you have selected). - **Canvas** — A resizable grid where each widget lives. Drag to move, drag an edge to resize. Your layout saves automatically. - **Widget library** — The panel you add widgets from. Describe a chart in plain language, pick from suggestions, browse chart kinds, or reuse a widget you already built. - **Inspector** — The right-hand panel that configures the selected widget: its data, its chart kind, and its styling. (Select a widget to open it.) - **Filters** — Dashboard-wide controls (like a date range) that every widget responds to at once. ![The dashboard editor showing several widgets placed on a resizable grid canvas, including charts and KPI tiles arranged across the layout.](https://cdn.banksync.io/screenshots/dashboards/editor-canvas.440b6387416c1d58.png "The canvas: widgets arranged on the editable grid.") ### What a widget can be A widget is not only a line chart. When you add one you choose a **kind**, and the catalog is broad: - **Charts**: lines, areas, bars and columns, pies and donuts, plus many more specialized kinds (treemaps, heatmaps, box plots, and so on) for when you need them. - **Big-number KPIs**: a single headline figure (like total spend this month), optionally with a comparison arrow against the previous period and a small trend sparkline. - **Gauges**: a dial that shows progress toward a goal with green / amber / red bands, good for things like a savings-rate target. - **Tables**: rows of data with rich, per-column formatting. Columns are not just plain text: they can render as currency, status pills, progress bars, mini sparklines, ratings, links, and more, so a table can be as readable as a chart. You are never locked into your first choice. Switch a widget's kind in the inspector at any time, and BankSync carries over the fields you have already bound. ![The add-a-widget library panel open on the All tab: a searchable catalog of widget kinds, each card showing a live mini-preview of the chart, KPI, or table.](https://cdn.banksync.io/screenshots/dashboards/widget-library.6cffd620d6bd6a6f.png "The widget library: a searchable catalog of every widget kind, each with a live preview.") ![The inspector configuring a KPI widget that sums an Amount field, with the comparison delta-arrow enabled and an area sparkline turned on.](https://cdn.banksync.io/screenshots/dashboards/kpi-inspector.5bdeea912beded3c.png "The inspector configuring a KPI widget, with a comparison arrow and a trend sparkline turned on.") ![A date-range filter control set to a 90-day preset spanning 2026-01-01 to 2026-05-31.](https://cdn.banksync.io/screenshots/dashboards/filter-date-range.2df8de4db810be98.png "A dashboard-wide date-range filter: change it once and every widget updates.") > **Let an agent build it:** You do not have to place every widget by hand. If you drive BankSync through an AI agent, you can > ask the agent to create whole dashboards and widgets for you (this is available in beta, alongside > the in-app Dashboards feature). ## Two ways to start - **A blank dashboard** — Start from an empty canvas and add widgets one at a time. Good when you know what you want to see. - **A template** — Start from a prebuilt dashboard, point it at your feeds, and tweak from there. Good for a fast, polished start. ![The dashboard template gallery showing prebuilt dashboard cards a user can pick to instantiate.](https://cdn.banksync.io/screenshots/dashboards/template-gallery.85b7935e184d8fca.png "The template gallery: pick a prebuilt dashboard and point it at your own feeds.") A brand-new dashboard is a draft until you give it a name, add a widget, or add a filter. Once you do, BankSync saves it for real and it appears in your dashboards list. Until then it stays an unsaved scratch space, so you can experiment without cluttering your workspace. ### A worked example The fastest way to understand all of this is to build one widget end to end. Say you want to see what you spent each month, broken down by category: 1. Open a blank dashboard and click **Add a widget**. 2. In the **Ask** tab, type `spending by month by category`, or pick a **Bar** chart from the chart kinds. 3. Point the widget at your **Transactions** feed. 4. Group by **Category**, and set the value to **Sum of Amount**. That is it. The widget renders, and your spend-by-category chart updates every time the dashboard loads. From here you can switch it to a different chart kind, add a date-range filter, or drop in a KPI for total spend. ## There is no view mode and no save button For you as the author, BankSync dashboards are **always editable**. There is no separate "edit" and "view" mode to toggle between, and there is no Save button. Every change you make (moving a widget, renaming the dashboard, editing a chart) is saved automatically a moment after you make it. A small status badge in the toolbar shows **Saving** while a change is in flight and **Saved** once it lands. ![The dashboard editor's toolbar showing the Undo and Redo actions, a Filters toggle, a Fullscreen button, the Widgets button, and a primary Share action.](https://cdn.banksync.io/screenshots/dashboards/editor-toolbar.9fc2fb56ca4ea37b.png "The editor toolbar. The autosave status badge sits here, switching between Saving and Saved as your changes land.") > **What people you share with see:** "No view mode" applies to you, the author. When you publish a dashboard, the people you share > it with see a separate, read-only view: they can read and filter it, but they cannot edit your > widgets or layout. See Publishing and sharing for how > that works. ## Where to go next **Recommended path** 1. **Create your first dashboard** — Open a blank canvas and learn the editor layout and keyboard shortcuts. 2. **Add a widget** — Use the library to add your first chart, KPI, or table. 3. **Connect it to your data** — Point the widget at a feed (or a live bank source), then pick what to group by and measure. This is what "binding data" means: telling the widget which numbers to show. 4. **Pick a chart kind** — Browse the chart catalog and choose how to draw it. You can switch kinds at any time. 5. **Try KPIs, tables, and gauges** — Not everything is a chart. Add a headline number, a formatted table, or a goal gauge. 6. **Publish or embed** — Share a read-only link or embed a widget in your own site. ## Related guides - [Creating your first dashboard](/docs/dashboards/creating-a-dashboard): the editor, shortcuts, and autosave. - [Adding widgets](/docs/dashboards/adding-widgets): the library and the four ways to add a widget. - [Binding data](/docs/dashboards/binding-data): group by, value, aggregation, and bucketing. - [Chart kinds](/docs/dashboards/chart-kinds): the full catalog and which one to reach for. - [KPI, table & gauge widgets](/docs/dashboards/kpi-table-gauge): the non-chart widget kinds and their formatting. - [Templates](/docs/dashboards/dashboard-templates): start from a prebuilt dashboard. - [Organizing dashboards](/docs/dashboards/organizing-dashboards): folders, renaming, and keeping a tidy list. - [Publishing and sharing](/docs/dashboards/publishing-and-sharing): read-only links and embeds. - [Create your first feed](/docs/bank-feeds/creating-first-feed): get data flowing before you chart it. [Create your first dashboard](/docs/dashboards/creating-a-dashboard) --- # Creating Your First Dashboard > Start from a blank canvas, a template, or an AI agent, learn the editor layout and keyboard shortcuts, and understand how autosave and drafts work. > Source: https://banksync.io/docs/dashboards/creating-a-dashboard A new dashboard starts as a blank canvas. You add widgets to it, arrange them on a grid, and BankSync saves your work as you go. This guide covers what you see when you land, the editor layout, the keyboard shortcuts that speed it up, and how drafts and autosave behave. > **Prerequisites:** 'You need a workspace where Dashboards is enabled and at least one feed with synced data (so your widgets have something to chart). See Bank feeds → Create your first feed if you have not set one up.' > **Availability:** Dashboards are in beta and roll out per workspace. If you do not see Dashboards in your left navigation, it is not enabled for your workspace yet, so the steps below will not be available. (In that case the dashboards address shows a 'not found' page rather than the editor.) [![Creating a dashboard from scratch: clicking New in the dashboards tree, naming it Runway, the empty first-run canvas, adding the first widget from the library, and the autosave badge confirming.](https://cdn.banksync.io/videos/create-a-dashboard.poster.8b6880e2f7e445b9.png)](https://cdn.banksync.io/videos/create-a-dashboard.b083298a97efe131.mp4) [Watch: Creating a dashboard from scratch: clicking New in the dashboards tree, naming it Runway, the empty first-run canvas, adding the first widget from the library, and the autosave badge confirming.](https://cdn.banksync.io/videos/create-a-dashboard.b083298a97efe131.mp4) ## Start a new dashboard Open **Dashboards** in the left navigation and choose **New dashboard**. You land on an empty canvas. A card in the middle of it reads **Nothing here yet**, with the subtext "Ask a question or pick a chart to start." This card is your launch pad. ![A new dashboard's empty canvas with a centered 'Nothing here yet' card, an 'Add a widget' button, and 'Pick a chart kind' and 'Browse dashboards' links.](https://cdn.banksync.io/screenshots/dashboards/empty-canvas.a6672d56f1853c5e.png "A brand-new dashboard opens to the 'Nothing here yet' launch card on a blank canvas.") From that card you can start in any of these ways: - **Add a widget** — The primary button. It opens the widget library on the right so you can describe a chart, pick from suggestions, or browse chart kinds. - **Pick a chart kind** — Jumps straight to the chart picker so you can choose a shape (line, bar, KPI, and so on) before binding it to your data. - **Browse dashboards** — Takes you back out to your existing dashboards if you opened a new one by mistake. If you have opened dashboards before, a **Recent:** row of chips appears under the buttons so you can jump back into one. On a brand-new dashboard, a **Start from a template** gallery also appears below the card. Picking a template builds a ready-made dashboard for you and opens it, which is the fastest start if you are not sure what to chart. See [Dashboard templates](/docs/dashboards/dashboard-templates) for the full list. > **More than one way in:** '"New dashboard" is not the only entry point. Visiting the Dashboards page directly, or using the New dashboard button in the content tree on the left, lands you on the same blank canvas. If you arrived here from the launch card above, just use Add a widget rather than hunting for a New dashboard button.' ## The editor at a glance Once you start adding widgets, the editor settles into three regions. A **widget** is a single tile (a chart, a big-number KPI, or a table); the **canvas** is the grid they sit on; and the **inspector** is the right-hand panel where you configure whichever widget you have selected. - **Content tree (left)** — Your dashboards and folders. Show or hide it with the left bracket key (\[) so the canvas can use the full width. - **Canvas (center)** — The grid your widgets live on. Drag a widget to move it, drag an edge to resize. - **Inspector & library (right)** — Add widgets from the library, then configure the selected widget in the inspector. ![The dashboard editor with several widgets placed on the grid canvas (a KPI tile, a chart, and a table), the first widget selected with a highlight ring.](https://cdn.banksync.io/screenshots/dashboards/editor-canvas.440b6387416c1d58.png "The canvas with widgets placed: the content tree sits on the left, the library and inspector on the right.") ![The left-rail content tree showing nested folders, an active dashboard, and an Unfiled group, with a New dashboard control.](https://cdn.banksync.io/screenshots/dashboards/content-tree.d5aea2a845994db8.png "The content tree on the left lists your dashboards and folders. Toggle it with the left bracket key.") The strip across the top is the editor toolbar. It carries the action buttons you reach for while editing: Undo and Redo, the Filters toggle, Fullscreen, Widgets (the library), and Share. ![The dashboard editor's action toolbar: Undo, a disabled Redo, an active Filters toggle, Fullscreen, Widgets, and a primary Share button.](https://cdn.banksync.io/screenshots/dashboards/editor-toolbar.9fc2fb56ca4ea37b.png "The editor toolbar's action buttons: Undo and Redo, Filters, Fullscreen, Widgets, and Share. The dashboard title and the Saving/Saved badge sit alongside it.") ## Keyboard shortcuts A few keys make the editor faster. They work whenever your cursor is not in a text field. - **\[ — Dashboards** — Show or hide the content tree on the left. - **] — Library** — Show or hide the widget library on the right. - **f — Fullscreen** — Hide the navigation and both side panels for a distraction-free, full-width canvas. The matching toolbar button is labeled Fullscreen (and Exit fullscreen while you are in it). > **Undo and redo:** 'Undo and Redo cover recent layout changes (moving and resizing widgets) so you can recover if you nudge something out of place. Use the toolbar buttons, or press Cmd+Z / Ctrl+Z to undo and Shift+Cmd+Z / Shift+Ctrl+Z to redo. The history is for layout only: adding or removing a widget is not part of undo (remove it from the inspector instead).' ## Drafts and autosave A brand-new dashboard is a **draft**: an unsaved scratch space that does not appear in your dashboards list yet. BankSync turns it into a real, saved dashboard the moment you do something meaningful with it. **When a draft becomes a saved dashboard** 1. **You name it** — Give the dashboard a title in the toolbar. 2. **You add your first widget** — Drop any widget onto the canvas. 3. **You add your first filter** — Create a dashboard filter. 4. **You pick a template** — Choosing a template from the launch card builds and opens a saved dashboard right away, with no naming or widget step required. As soon as one of those happens, the dashboard is saved, its address in your browser changes to its permanent link, and it shows up in your dashboards list. From then on, **every change saves automatically** a moment after you make it. The toolbar shows **Saving** while a change is in flight and **Saved** once it is stored. There is no Save button to press. ![The dashboard editor's title strip showing the 'Cashflow' dashboard name beside a green check and a 'Saved' badge, with the content-tree toggle and the Widgets and Share toolbar buttons.](https://cdn.banksync.io/screenshots/dashboards/editor-autosave.7950283f12c3aab8.png "After a change is stored, the toolbar shows a green check and a 'Saved' badge next to the dashboard name. No Save button to press.") > **Exploring will not create a stray dashboard:** 'Only the actions above commit a draft. Clicking around (opening the widget library, toggling the side panels, pressing the keyboard shortcuts, or browsing chart kinds) does not save anything, so you can explore the editor freely. Nothing lands in your dashboards list until you name it, add a widget or filter, or pick a template.' > **Sharing needs a saved dashboard:** 'An unsaved draft has no Share option yet, because there is nothing permanent to link to. Name the dashboard or add a widget first, then the Share action appears. See Publishing & sharing for details.' ## A quick worked example Here is a start-to-finish run so you can see how the pieces fit together: **Build a 'Cashflow' dashboard** 1. **Open a new dashboard** — From the Dashboards page, choose New dashboard. The "Nothing here yet" card appears. 2. **Name it** — Type "Cashflow" into the title field in the toolbar. The dashboard saves and gets its own link the moment you name it. 3. **Add your first widget** — Click Add a widget to open the library, then describe what you want, for example "spending by month", and add the suggested chart to the canvas. 4. **Arrange it** — Drag the widget where you want it and drag an edge to resize. The toolbar flashes Saving, then Saved. 5. **Keep going** — Add more widgets the same way. Everything you do keeps saving on its own, so you can close the tab whenever you like. ## Create with an AI agent (beta) You do not have to build everything by hand. If you drive BankSync through an AI agent (for example Claude), the agent can create dashboards, folders, widgets, and queries for you using BankSync's dashboard tools, then publish them. This authoring path is in beta and currently available in staging environments only, so it may not be present in your production workspace yet. The in-app **Ask** tab in the widget library offers a similar plain-language on-ramp without an external agent (see [Adding widgets](/docs/dashboards/adding-widgets)). ## Related guides - [Adding widgets](/docs/dashboards/adding-widgets): the four ways to add a widget to the canvas. - [Pick a chart kind](/docs/dashboards/chart-kinds): the full catalog of chart shapes and when to use each. - [KPI, table & gauge widgets](/docs/dashboards/kpi-table-gauge): the non-chart widgets for single numbers, formatted rows, and goal dials. - [Organizing dashboards](/docs/dashboards/organizing-dashboards): folders, renaming, and the content tree. - [Dashboard templates](/docs/dashboards/dashboard-templates): start from a prebuilt dashboard instead of a blank one. [Add your first widget](/docs/dashboards/adding-widgets) --- # Customizing Home > Turn the dynamic Home page into a protected workspace dashboard, add native BankSync widgets, arrange the layout, and reset it safely. > Source: https://banksync.io/docs/dashboards/customizing-home Home is the first page members see when they open a workspace. Before you customize it, Home is dynamic: BankSync picks a useful layout from the workspace's current banks, integrations, feeds, portals, enrichments, and recent sync activity. Customizing Home turns that dynamic view into a protected workspace dashboard. From then on, Home uses the layout and widgets your team chose, while still opening in view mode by default so normal clicks open resources instead of moving cards. [![Customizing Home: starting from the dynamic workspace Home page, switching into Customize, adding native widgets such as feed activity, and saving Home as a protected shared dashboard.](https://cdn.banksync.io/videos/home-customization.poster.8a5c7de062bce622.png)](https://cdn.banksync.io/videos/home-customization.8e8144b17dff1b42.mp4) [Watch: Customizing Home: starting from the dynamic workspace Home page, switching into Customize, adding native widgets such as feed activity, and saving Home as a protected shared dashboard.](https://cdn.banksync.io/videos/home-customization.8e8144b17dff1b42.mp4) > **Who can customize Home:** You need Editor access or higher to customize, reset, or launch setup actions from Home. Viewers > can read Home and open resource pages, but they cannot connect banks, connect integrations, create > feeds, or change the shared Home layout. ## How Home is different from a normal dashboard Home uses the dashboard canvas and widget system, but it has a few extra rules because it is the workspace landing page: - **Dynamic until edited** — A new workspace does not store a Home dashboard immediately. BankSync renders the best current recipe until an editor customizes it. - **Protected after editing** — The first edit saves Home as a protected workspace dashboard. It appears in Dashboards, but cannot be deleted, moved, published, or embedded through generic dashboard actions. - **Native widgets** — Home can use platform widgets such as account balances, connected banks, integrations, feed activity, recent sync runs, portals, and enrichment summaries. - **View-first on mobile** — Mobile users get a readable single-column stack derived from the desktop layout. Mobile authoring is intentionally not exposed yet. ![The dashboard editor canvas with widgets arranged on a grid, showing the same grid surface Home uses after an editor customizes it.](https://cdn.banksync.io/screenshots/dashboards/editor-canvas.440b6387416c1d58.png "Customizing Home uses the same grid canvas as dashboards, but Home stays protected and opens in view mode.") ## Customize Home Open **Home** from the workspace navigation and choose **Customize**. BankSync copies the exact dynamic Home you were viewing into a persisted Home dashboard, then switches the page into edit mode. In edit mode you can: - Move and resize Home widgets. - Add native BankSync widgets from the widget library. - Pin reusable dashboard widgets onto Home. - Remove widgets that do not belong on the landing page. - Finish editing and return Home to view mode. ![The dashboard editor toolbar with widget, filter, fullscreen, undo, redo, and share controls; Home uses the same toolbar pattern for customization actions.](https://cdn.banksync.io/screenshots/dashboards/editor-toolbar.9fc2fb56ca4ea37b.png "The editor toolbar is where you open the widget library, undo layout moves, and finish a customization pass.") > **Home is shared:** Customizing Home changes the workspace Home page for every member. Use the layout for information > the whole workspace should see first, not for personal scratch work. ## Add native widgets Choose **Widgets** while Home is in edit mode. Native widgets appear in the widget library alongside regular chart, table, KPI, and control widgets. They are app-aware widgets: instead of reading a single query, they render BankSync product surfaces inside the dashboard grid. Good native widgets for Home include: - **Feed activity** for the sync heatmap, recent runs, failures, and history links. - **Bank account balances** for connected account totals and attention states. - **Connected banks** and **connected integrations** for quick resource navigation. - **Feeds summary** for pipeline health. - **Portals** and **enrichments** summaries when those tools are central to the workspace. ![The dashboard widget library open on the All tab with searchable widget cards and previews; Home native widgets are added from this same library surface.](https://cdn.banksync.io/screenshots/dashboards/widget-library.6cffd620d6bd6a6f.png "Add native widgets from the widget library, then place them on the Home grid.") Native widgets stay inside the authenticated app. A dashboard that contains native app widgets cannot be published publicly or embedded, because those widgets depend on workspace permissions and live BankSync workflows. ## Reset Home If the customized layout stops being useful, choose **Reset Home** from Home. Resetting removes the protected Home dashboard and the system widgets BankSync created for it. Reusable user-created widgets that were only pinned onto Home are kept. After reset, Home goes back to the dynamic recipe and adapts again as banks, integrations, feeds, portals, enrichments, and sync activity change. > **Reset affects the whole workspace:** Reset only appears for editors, but it still changes the shared Home page for everyone. Use it > when the team wants to return to BankSync's dynamic default. ## Related guides - [Dashboards overview](/docs/dashboards/dashboards-overview): how the dashboard canvas and widget system work. - [Adding widgets](/docs/dashboards/adding-widgets): how to use the widget library. - [Organizing dashboards](/docs/dashboards/organizing-dashboards): how the protected Home dashboard appears in dashboard management. - [Publishing and sharing](/docs/dashboards/publishing-and-sharing): why dashboards with native widgets cannot be published or embedded. --- # Organizing Dashboards with Folders > Use the content tree to rename, duplicate, search, reorder, and file dashboards into folders, and understand exactly what deleting a dashboard or a folder does. > Source: https://banksync.io/docs/dashboards/organizing-dashboards As you build more dashboards, the **content tree** on the left keeps them organized. It is a folder tree of all your dashboards: you can rename them, give them icons, duplicate them, drag them into folders, and reorder them. To open or hide it, click the panel toggle (the left-panel icon in the editor's title strip). If you prefer the keyboard, the left bracket key `[` does the same thing. ![The content tree panel on the left side of the app: nested folders (Business with a Reports folder inside it), an active dashboard named Cashflow, and a synthetic Unfiled group for dashboards that are not in any folder. Each dashboard has an emoji icon.](https://cdn.banksync.io/screenshots/dashboards/content-tree.d5aea2a845994db8.png "The content tree keeps every dashboard organized into folders, with an Unfiled group for anything not yet filed.") > **A worked example to follow along:** 'Say you have eight dashboards piling up at the top level. By the end of this page you will be able to: create a Monthly reports folder, drag Cashflow and Runway into it, give Cashflow a 💰 icon and rename it, then reorder the two so Cashflow sits on top. Each step below maps to one part of that flow.' ## Working with a dashboard Hover a dashboard in the tree and open its menu (the three-dots icon) for its actions. - **Rename & icon** — Rename a dashboard inline, either by choosing Rename from its menu or by double-clicking its name in the tree. (A single click opens the dashboard, so use a double-click when you mean to rename.) Click its icon to pick an emoji or symbol so it is easy to spot. - **Duplicate** — Make a copy with the same layout, filters, and widgets, named "… (copy)". The layout and filters are the copy's own, but the widgets are shared, not cloned (see the caution below). - **Move to a folder** — Drag a dashboard onto a folder to file it there, or use the move action in its menu. - **Reorder** — Drag dashboards up and down to set the order they appear in. The order is one workspace-wide list, not a per-folder order, so a dashboard you drag can move relative to all the others. > **Duplicate shares widgets, it does not clone them:** Duplicate gives you a fresh dashboard with its own copy of the layout and filters, so rearranging tiles or changing a filter on the copy is safe. The widgets themselves are shared between the original and the copy (they are the same saved widgets, pinned to both). That means editing a shared widget's data, chart kind, columns, or title on the copy also changes it on the original. If you want a chart you can edit in isolation, build a brand-new widget on the copy (from the Add a widget panel) instead of editing the shared one. The duplicate is mainly useful for trying a different layout or filter set over the same charts. > **Finding a dashboard fast:** At the top of the content tree there is a Search dashboards… box. Type any part of a dashboard's name (or the name of the folder it lives in) and the tree flattens into a single matching list so you do not have to expand folders by hand. Drag-and-drop is paused while a search is active; clear the box to go back to the full folder tree and resume organizing. ## Folders Folders group related dashboards (for example "Monthly reports" or "Client A"). Create a folder from the tree, drag dashboards into it, and nest folders inside other folders for deeper structure. Folders can also have their own emoji or symbol icon, the same way dashboards do: click the icon next to a folder's name to pick one. Dashboards that are not in any folder live in an **Unfiled** group at the top level, so nothing ever gets lost. **Create and fill a folder** 1. **Create the folder** — Click the + New button at the top of the content tree and choose New folder, then type a name (for example "Monthly reports") and press Enter. 2. **Add dashboards** — Drag dashboards onto the folder (for example drag Cashflow and Runway in), or use a dashboard's move action to file it. 3. **Nest if you like** — Drag one folder onto another to nest it. The same **+ New** button also has a **New dashboard** option, so you can start a fresh dashboard right from the tree. ## Deleting Deleting always asks you to confirm first, and the two kinds of delete behave differently. Deleting a dashboard is the one action on this page you cannot undo, so it is worth understanding before you click. > **Deleting a dashboard is permanent:** 'Deleting a dashboard removes it along with its layout, its widget arrangement, and its filters. This cannot be undone, so the confirmation dialog spells out what will be lost. The widgets themselves are not deleted: they stay in your widget library, so any other dashboard that uses them is unaffected, and you can reuse them again later.' > **Deleting a folder keeps its contents:** Deleting a folder never destroys what is inside it. The dashboards that were in the folder are not deleted: they reappear under the Unfiled group at the top level, so you can refile them wherever you like. Only the folder itself is removed. If a folder still has subfolders inside it, empty or move those out first; a folder that still contains subfolders can't be deleted in one step (you will be asked to clear them first rather than have the whole subtree silently wiped). ![The delete-confirm dialog for a folder named 'Reports for accountants', with non-destructive reassurance copy explaining that the dashboards inside it move to Unfiled and only the folder itself is removed.](https://cdn.banksync.io/screenshots/dashboards/delete-folder-confirm.fc62ec52b8aa0b3d.png "The folder delete dialog reassures rather than warns: its dashboards reappear under Unfiled, nothing inside is destroyed.") ## Organizing with an AI agent If you drive BankSync through an AI agent (for example Claude with the BankSync tools), the agent can do this housekeeping for you: create folders, create or move dashboards into them, and delete dashboards on your behalf, all without you touching the tree by hand. This is available in the beta/staging environment while Dashboards is rolling out, so it may not appear in your account yet. Everything above still works exactly the same when you organize by hand. ## Related guides - [Creating your first dashboard](/docs/dashboards/creating-a-dashboard): the editor and autosave. - [Dashboards & widgets overview](/docs/dashboards/dashboards-overview): how the pieces fit together. - [Add widgets to a dashboard](/docs/dashboards/adding-widgets): build, reuse, and remove the charts inside a dashboard. [Add widgets to a dashboard](/docs/dashboards/adding-widgets) --- # Adding Widgets > Add charts, KPIs, and tables to a dashboard: browse the full widget catalog, reuse a widget you already built, or ask an AI agent. > Source: https://banksync.io/docs/dashboards/adding-widgets Widgets are the building blocks of a dashboard: each one is a chart, a KPI, a table, or another visual tied to your data. You add widgets from the **library**, which you open with the `]` key or the **Widgets** button in the editor toolbar. The library has three tabs, each a different way to get to the widget you want. ![The add-a-widget library panel open on the All tab: a searchable catalog of widget kinds, each card showing a live mini-preview of the chart, KPI, or table.](https://cdn.banksync.io/screenshots/dashboards/widget-library.6cffd620d6bd6a6f.png "The widget library: a searchable catalog of every widget kind, each with a live preview.") [![Adding a widget to a dashboard: opening the widget library with live data previews, clicking a KPI card so it lands on the canvas ready to bind, and dragging and resizing widgets with the layout autosaving.](https://cdn.banksync.io/videos/add-a-widget.poster.19191b5999f0c031.png)](https://cdn.banksync.io/videos/add-a-widget.7a3ea6b5cb3d4310.mp4) [Watch: Adding a widget to a dashboard: opening the widget library with live data previews, clicking a KPI card so it lands on the canvas ready to bind, and dragging and resizing widgets with the layout autosaving.](https://cdn.banksync.io/videos/add-a-widget.7a3ea6b5cb3d4310.mp4) ## The three ways to add a widget - **All** — The full catalog of widget kinds — every chart type plus KPI, table, text, image, embed, filter, and action. Search it, preview each card live, and click or drag to add a fresh widget. - **Dashboard** — The widgets already on this dashboard, in one place. Edit one (opens the inspector) or remove it from the dashboard. - **Workspace** — Every widget you have already built. Reuse one across dashboards without rebuilding it. A quick gloss of the terms that come up below: a widget is **pinned** to a dashboard (it appears there, but the underlying widget is shared, not copied); the **inspector** is the settings panel that opens when you select a widget; and to **detach** a widget is to remove it from one dashboard without deleting it. > **Another way: ask an AI agent (staging):** 'If you drive BankSync through an AI agent (for example Claude using the BankSync tools), the agent can create dashboards, widgets, queries, and folders for you. These authoring tools are available in staging while Dashboards is in beta and are not yet on in production.' ## Browsing the catalog The **All** tab is where most widgets start. It lists every widget kind — charts (line, area, bar, column, donut, and the rest), KPIs, tables, text notes, images, embeds, filter controls, and action buttons — with a search box at the top and a live mini-preview on each data-bound card. Type to narrow the list (for example "donut" or "table"), then add the one you want. **Add a widget from the catalog** 1. **Open the library** — Press the bracket key, or click Widgets in the toolbar. 2. **Find a kind** — Stay on the All tab and scroll, or type a word like "kpi" or "bar" to filter. 3. **Preview it** — Each data-bound card shows a live mini-preview rendered against sample rows. 4. **Add it** — Click the card to drop it at the next open spot, or drag it onto the canvas to place it precisely. > **Worked example: spending by category:** 'Open the library with ], type "bar" in the All tab, and add a bar chart. Then select it to open the inspector, point it at a feed, group by category, and sum the amount. Drag a corner to make it wider. To change anything later (the grouping, the chart kind, the colors), adjust it in the inspector. See Binding data for the field-by-field details.' Whatever kind you start from, you can switch it in the inspector after placing it. This includes the less common kinds (treemap, radar, boxplot, sankey, sunburst, calendar heatmap, and similar): each one gives you a working field editor for picking the columns it needs, so you are not limited to the everyday charts. ![The chart-kind picker showing the full catalog (line, area, bar, donut, pie, treemap, boxplot, heatmap, gauge, KPI, table and more) grouped by family, with a search box.](https://cdn.banksync.io/screenshots/dashboards/chart-kind-picker.c5378e8eb2fde88e.png "Starting a brand-new dashboard, the chart-kind picker offers the same catalog grouped by family.") Gauge, meter, and progress are **chart kinds** (the "single value" family), so you find them in the catalog alongside line, bar, and the rest. ## Placing a widget: click or drag This works the same way no matter which tab you added from. Clicking a library entry adds the widget at the next open spot on the grid. To place it precisely, **drag** it from the library onto the canvas: a ghost outline shows where it will land before you drop it. Once placed, drag the widget to move it and drag an edge to resize. The layout saves automatically. On a brand-new, empty dashboard you do not even need to open the library first: the canvas shows an **Add a widget** prompt that opens the same chooser. ![An empty dashboard canvas with a 'Nothing here yet' card and an 'Add a widget' button, the on-canvas prompt that opens the widget chooser on a brand-new dashboard.](https://cdn.banksync.io/screenshots/dashboards/empty-canvas.a6672d56f1853c5e.png "On a new dashboard, the empty canvas itself prompts you to add your first widget.") ![A single widget placed and fully rendered in its cell on the dashboard grid, sitting in an open spot alongside the surrounding layout.](https://cdn.banksync.io/screenshots/dashboards/widget-cell.7c2ade81421397ea.png "A widget settled into place on the grid after being dropped.") ## Reusing a widget you already built The **Workspace** tab lists every widget in your workspace. Adding one from here **pins** it onto the current dashboard rather than making a copy: it is the same widget, shown in more than one place. Edit it once and the change shows everywhere it is pinned. Each entry shows how many dashboards use it (for example "Used on 3 dashboards") and marks the ones already pinned to the current dashboard, so you can see at a glance whether changing it will ripple to other dashboards. > **Pinning is not copying:** 'Adding from Workspace pins the existing widget; editing it updates every dashboard that pins it. If you want an independent variant, duplicate the dashboard (which keeps its own pins) or build a fresh widget from the All tab instead.' ## More than charts Not every widget is a chart. The **All** tab lists every kind, charts and non-charts alike — search or scroll to find these: - **KPI** — A single big number with an optional comparison and sparkline. - **Table** — A formatted, paginated table of rows. Each column can be styled per its meaning: currency, percent, status pills, progress bars, mini sparklines, ratings, chips, links, and more. - **Text** — A Markdown note for headings, context, or instructions. - **Image & Embed** — A static image or an embedded external page. - **Filter & Action** — A filter control, or a button that runs a workspace action. - **Custom widget (beta)** — For developers: author your own widget in TypeScript against the BankSync widget SDK. > **Tables are richly formatted:** A table is not just plain text. Pick a format per column so each value reads the way a finance reader expects: amounts as currency, rates as percentages, states as colored status pills, completion as a progress bar, a trend as a tiny inline sparkline, plus dates, durations, ratings, chips, links, and images. Set this up in the table's column manager in the inspector. See KPI, table & gauge widgets for the full list. ## Removing a widget from a dashboard There are two ways to take a widget off a dashboard, and both ask you to confirm: - From the **Dashboard** tab of the library, find the widget and click its **trash** icon. - Or **select the widget** on the canvas (its settings open in the inspector) and click **✕ Remove from dashboard** at the bottom of the inspector. Either way this detaches it from **this** dashboard only: the widget stays in your library, so any other dashboard that pins it is unaffected and you can re-add it later. ![The widget inspector right rail with the Data/Style/Share/Advanced tabs and finance fields, ending in a pinned destructive footer button reading 'Remove from dashboard'.](https://cdn.banksync.io/screenshots/dashboards/inspector-shell.12d13c6f0c4fb8fa.png "The Remove from dashboard button lives at the bottom of the inspector, below the tabs.") ## Related guides - [Binding data](/docs/dashboards/binding-data): point a widget at a feed and choose what to group by and measure. - [The chart kind catalog](/docs/dashboards/chart-kinds): every chart kind and when to use it. - [KPI, table & gauge widgets](/docs/dashboards/kpi-table-gauge): configure the non-chart widget types, including a table's per-column formats. - [Templates](/docs/dashboards/templates): the portable way to reuse a widget or a whole dashboard layout across workspaces. - [Publishing and sharing](/docs/dashboards/publishing-and-sharing): share a widget or dashboard with people outside the editor. [Bind a widget to your data](/docs/dashboards/binding-data) --- # The Chart Kind Catalog > Browse every chart kind BankSync can render, grouped by what they are good at, with a quick start for the everyday kinds and how switching kinds reuses your data binding. > Source: https://banksync.io/docs/dashboards/chart-kinds Every data-bound widget renders as one **chart kind**. BankSync supports a large catalog of kinds. You pick a kind when you add a widget and can switch it any time later. Switching reuses the fields you already bound, so trying line, then area, then column is usually a one-click experiment, not a rebuild. [![Adding a dashboard widget: opening the widget library, browsing chart and KPI cards with live previews, adding a KPI to the canvas, binding it to a feed, and publishing or embedding the result.](https://cdn.banksync.io/videos/add-a-widget.poster.19191b5999f0c031.png)](https://cdn.banksync.io/videos/add-a-widget.7a3ea6b5cb3d4310.mp4) [Watch: Adding a dashboard widget: opening the widget library, browsing chart and KPI cards with live previews, adding a KPI to the canvas, binding it to a feed, and publishing or embedding the result.](https://cdn.banksync.io/videos/add-a-widget.7a3ea6b5cb3d4310.mp4) > **Not sure which one to pick?:** Most finance and ops dashboards only need a handful of kinds. Start with one of these and switch later if it doesn't fit:Line for a value over time (balance, daily spend).Bar / Column to compare a value across categories (spend by merchant).Pie / Donut for a few categories' share of a total.KPI for a single headline number (this month's spend).Table for the underlying rows.The rest of this page is a reference catalog. The everyday kinds above are listed first in each group, and the more specialized kinds (Stream, Beeswarm, Sankey, Chord, and so on) follow for when you need them. ## Two places you pick a kind There are two pickers, and they group the kinds slightly differently. Both reach the same catalog. - **The first-pick picker** appears on an empty canvas under the heading **What do you want to see?** It groups kinds by visual family: Trend, Composition, Hierarchy, Distribution, Matrix, Single value, Relational, and Financial. You pick the look first, then the inspector prompts you for the fields. - **The Chart type picker** lives in the **inspector** (the panel that opens when you select a widget). It groups kinds by the question they answer: Time series, Comparison, Part-of-whole, Distribution, Correlation, Flow / network, Matrix / heatmap, Radial, Financial, and Single value. Use it to switch an existing widget's kind without losing your bound fields. The tables below follow the inspector's "question" grouping, since that is where you spend most of your time once a widget exists. ![The empty-canvas chart picker titled 'What do you want to see?', showing chart kinds grouped by visual family (Trend, Composition, Hierarchy, Distribution, Matrix, Single value) as labeled cards with emoji badges and a search box at the top.](https://cdn.banksync.io/screenshots/dashboards/chart-kind-picker.c5378e8eb2fde88e.png "The first-pick picker on an empty canvas, grouped by visual family with a search box. The inspector's Chart type picker groups the same kinds by question instead.") In the inspector, the Chart type dropdown lists the same kinds under question-based headings (Time series, Comparison, Part-of-whole, and so on), so you can switch an existing widget's kind from there without leaving its field bindings. ## A worked example Say you want to see **spend per category** from your Transactions feed: 1. Add a widget and point it at your **Transactions** feed. 2. In the **What do you want to see?** picker, choose **Bar** (under Trend) or open the inspector's **Chart type** picker and choose **Bar / Column** (under Comparison). 3. In the inspector, set **Group by** to **Category** and **Value** to the sum of **Amount**. 4. To see the same numbers as a ranked list instead, switch the kind to **Lollipop / Dot**: your Category and Amount stay bound, so it is a one-click change. That is the whole loop: pick a kind, bind a category and a number, switch kinds freely. ## Time series Show how a value changes over time. These expect a date on one axis. | Kind | Use it for | | ------------ | ------------------------------------------------------------------- | | Line | A value over time (balance, spend per day). | | Area | A line with the area filled, to emphasize volume. | | Stacked area | Several series stacked to show the total and the mix. | | Stream | A flowing, center-aligned stacked area for shifting mixes. | | Step line | Values that hold then jump (like a balance after each transaction). | | Sparkline | A tiny inline trend with no axes, great inside a KPI. | ## Comparison Compare a value across categories. | Kind | Use it for | | ---------------- | -------------------------------------------------------- | | Bar / Column | Compare a measure across categories (spend by merchant). | | Grouped bar | Compare several measures side by side per category. | | Stacked bar | Show each category's total and its parts. | | 100% stacked bar | Compare the mix across categories, ignoring totals. | | Lollipop / Dot | A lighter bar alternative for ranked values. | | Bullet | A value against a target or threshold. | ## Part of a whole Show how parts add up to a total. These need a category to slice by. **Pie / Donut** is the everyday one; the rest are stylistic variations. | Kind | Use it for | | ------------------------ | ------------------------------------------------------------------------------------ | | Pie / Donut | A few categories' share of a total. | | Nightingale / Radial bar | A circular take on category comparison (a "rose" chart, bars drawn around a center). | | Treemap / Sunburst | Nested shares (category then subcategory). | | Mosaic / Waffle | Proportions as tiled blocks. | | Funnel / Pyramid | Stages that narrow from top to bottom. | ## Distribution Show how values are spread out. **Histogram** is the everyday one; the rest are specialized statistical views. | Kind | Use it for | | ------------------------- | ----------------------------------------------------------------------------- | | Histogram | How often values fall in each range (transaction sizes). | | Density / Ridgeline | A smoothed version of a histogram, one curve or several stacked. | | Box plot / Violin | The spread and outliers per category (the middle, the range, the stragglers). | | Strip / Beeswarm / Jitter | Every individual value as a dot, spread out so they don't overlap. | ## Correlation Show how two measures relate. **Scatter** is the everyday one; the rest handle very dense data or many measures at once. | Kind | Use it for | | -------------------- | --------------------------------------------------------------------- | | Scatter | Two measures plotted against each other. | | Bubble | A scatter with a third measure shown as the dot size. | | Hexbin / Contour | A scatter so dense that it is summarized by how crowded each area is. | | Parallel coordinates | Compare many measures across items on side-by-side scales. | ## Flow and network Show movement or relationships between things. These are specialized; reach for them when a bar or table can't show how amounts move between groups. | Kind | Use it for | | ----------------- | ---------------------------------------------------------------- | | Sankey / Alluvial | Flows between stages, drawn as ribbons (income into categories). | | Chord / Arc | Relationships between entities, drawn around or along an edge. | | Network | A graph of connected nodes. | ## Matrix and heatmap Show intensity across two dimensions as color. **Heatmap** and **Calendar heatmap** are the approachable ones. | Kind | Use it for | | ---------------------------- | ------------------------------------------------------------------- | | Heatmap / Heatmap matrix | A value across two categories, shown as color intensity in a grid. | | Correlation matrix | How every measure correlates with every other (a specialized grid). | | Calendar heatmap / Punchcard | Activity by day, or by day and hour, like a contribution calendar. | ## Radial, financial, and single value | Kind | Use it for | | ----------------------------------- | ----------------------------------------- | | Radar / Polar / Circular bar | Compare measures around a circle. | | Candlestick / OHLC / Volume profile | Price movement for investment data. | | Gauge / Meter / Progress | A single value against a scale or target. | The single-value kinds (Gauge, Meter, Progress) show one number against a scale or target rather than a series of points. A gauge is the most legible of the three for a goal like a savings rate. ![The gauge inspector for a savings-rate goal: a three-quarter gauge shape with a percentage unit and green, amber, and red color bands marking the target ranges.](https://cdn.banksync.io/screenshots/dashboards/gauge-inspector.f1cbe3981117d6d1.png "A gauge configured for a savings-rate goal, with color bands for on-track, warning, and off-track.") ## Switching kinds without losing work When you change a widget's kind in the inspector's **Chart type** picker, BankSync re-uses the fields you already bound (and their settings, like the grouping grain or the sum) and fills in only what the new kind adds. So line, area, and column swap freely. One thing to know: if you switch to a kind that holds fewer fields, the extras are dropped rather than kept. For example, a multi-series line carries a date, a number, and a series split. Switch it to a pie (which has room only for a category and a value) and the series split has nowhere to go, so it falls away. Switch back and you re-bind it. Within kinds of the same shape (line, area, column, bar) nothing is lost. If a kind cannot render your current data, the picker disables it and tells you why in plain language, for example "needs a category field" or "needs a number field" rather than naming internal field roles. Bind the missing kind of field and the option lights up. ![A widget cell showing a fix-it nudge because the same field is bound to both axes, with an inspector hint explaining how to correct the encoding.](https://cdn.banksync.io/screenshots/dashboards/widget-fix-it.03e4a9a4fac2982a.png "When a kind cannot render the current binding, the widget shows a plain-language fix-it nudge instead of a broken chart.") > **Financial kinds want price columns:** 'Candlestick, OHLC, and Volume profile expect Open, High, Low, and Close columns and recognize them by name. On plain transaction data they stay disabled with the message "needs Open/High/Low/Close fields". They are built for investment or market data, not spending.' > **Less common kinds are editable too:** 'The everyday chart kinds have purpose-built field controls, and the more specialized kinds (radar, treemap, box plot, heatmap matrix, calendar heatmap, sankey, gauge, and the like) now have a working field editor as well. Selecting one of these opens a panel that lists each field slot the kind uses, so you can bind and rebind them the same way.' > **Preview kinds:** 'The everyday chart kinds (line, area, bar, column, pie, donut, scatter, histogram) are fully styleable: legend, axes, grid, and title all respond. The newer and more specialized kinds render correctly but do not yet expose every styling control, so they carry a Preview badge to flag that their appearance options are still limited. The styleable set grows over time as more kinds are finished, so trust the Preview badge in the app rather than memorizing a list.' > **The catalog tracks the renderer:** 'The list of available kinds reflects what the chart engine can actually draw, so you only ever see kinds that will render. New kinds appear here as the renderer gains them.' ## Beyond charts KPI, Table, and the single-value kinds are covered in depth on their own page. Tables in particular do more than show plain rows: each column can be formatted as currency, a status pill, a progress bar, an inline sparkline, a rating, and more, all configured in the table's column manager. ![The table column manager showing a Date column card and an Amount column card, each with reorder grips and format, alignment, and pin controls, plus two more fields available to add.](https://cdn.banksync.io/screenshots/dashboards/table-inspector.354ae711218831ee.png "A table's column manager: reorder columns, set per-column format and alignment, and pin or add fields.") ## Related guides - [Binding data](/docs/dashboards/binding-data): choose the fields a chart kind needs. - [Adding widgets](/docs/dashboards/adding-widgets): start a widget of any kind. - [KPI, table & gauge widgets](/docs/dashboards/kpi-table-gauge): the non-chart kinds in depth. [Bind your data](/docs/dashboards/binding-data) --- # Binding Data: Group By, Value, Aggregation & Bucketing > Point a widget at a feed and shape it with the Group by, Value, and Split into series channels, time bucketing, and aggregation, with no formulas for the everyday path. > Source: https://banksync.io/docs/dashboards/binding-data Binding is how you tell a widget what to show: which feed to read, what to put on each axis, and how to summarize the numbers. You do it in the inspector's **Data** tab with plain controls, and the chart updates as you go. No formulas are needed for the everyday path (the Shape data dialog later on does let you write column expressions if you want them). The rich controls on this page (date bucketing, aggregate, Keep top N, Spending/Income/Net) appear for the common chart kinds that show their fields as labeled **chips**: line, area, bar, column, scatter, pie, donut, and the like, plus the KPI, table, and gauge widgets. A handful of less common kinds (radar, treemap, box plot, heatmap matrix, and a few others) show a simpler Data tab: one plain field picker per role (Category, Value, and so on), with no bucket or aggregate dials. If your widget shows simple field pickers instead of chips, that is expected for those kinds. > **Want to follow along? Build monthly spending:** 'A concrete run-through, end to end: pick your Transactions feed as the source, set Group by to Date bucketed by Month, set Value to Amount, leave the aggregate on Sum, and set Show amount as to Spending. You now have a clean bar of monthly spend. Every step below explains one of those dials.' [![Binding data to a widget through the inspector: selecting a chart, choosing a live Chase source, widening the window to a year, then grouping by month and summing amounts as spending so the chart re-aggregates live.](https://cdn.banksync.io/videos/bind-widget-data.poster.3db2e380aaeb1b50.png)](https://cdn.banksync.io/videos/bind-widget-data.194d7d3a37e1a26c.mp4) [Watch: Binding data to a widget through the inspector: selecting a chart, choosing a live Chase source, widening the window to a year, then grouping by month and summing amounts as spending so the chart re-aggregates live.](https://cdn.banksync.io/videos/bind-widget-data.194d7d3a37e1a26c.mp4) ## Choose a data source Each widget reads from one source. In the Data tab, pick the feed (or live bank source) the widget should chart. If you bound the wrong one, switch it here and your channel choices carry over where they still make sense: a field the new source also has (like Date or Amount) stays put, but any field the new source does not have is dropped, so a chip can come up empty after a switch. If that happens, just pick a replacement field from the now-empty chip. ![The widget inspector's Data tab showing the source picker, a list of feeds and live bank sources the widget can read from, with one source selected.](https://cdn.banksync.io/screenshots/dashboards/source-picker.bd30131c70192f79.png "Pick the feed or bank source the widget charts.") ## The channels A chart maps fields from your data onto visual roles. Each role is a labeled **chip** in the Data tab; tap a chip to pick its field and adjust how it behaves. Read each chip as the plain question it answers: - **Group by** — "What goes along the bottom?" The category or time field on the x-axis: merchant, category, or date. - **Value** — "What number am I measuring up the side?" The measure on the y-axis: amount, count, or balance. - **Split into series** — "Do I want one line per group?" An optional second category that splits one line or bar into several, one per value. Those are the three roles you will reach for on almost every chart. (Some kinds expose a Color chip too, which works like a second Group by.) ![The inspector Data tab Fields panel for a cartesian chart, with a Group by dimension chip (Merchant) stacked above a Value measure chip (Amount, summarized as sum, labeled spending).](https://cdn.banksync.io/screenshots/dashboards/data-channels.4455be55fad0722f.png "The Fields panel: a Group by chip stacked above a Value chip.") ![The Value channel chip in the inspector, summing Amount, labeled as spending, showing the chip's plain-English 'sum · spending' summary.](https://cdn.banksync.io/screenshots/dashboards/channel-measure.3101a680a16513f1.png "The Value channel chip, summing Amount as spending.") > **Charting two numbers at once (combo charts):** 'There is no separate "Second value" chip. To put a second measure on a chart (for example bars for spend plus a line for count), you add it through the chart\\'s own settings: bar-plus-line combos and a second y-axis are configured on the chart kind, not by a third channel. Start with one Value, then reach for the combo or secondary-axis option once the basics read right.' ## Bucketing dates When you Group by a date, you rarely want one point per day forever. Tap the date chip to open its **Bucket by** control and group dates into readable periods: | Bucket | Shows | | ----------------------------------- | ----------------------------------------- | | Day / Week / Month / Quarter / Year | One point per calendar period. | | Exact | Every individual timestamp, no bucketing. | Pick the period that tells the story (monthly for a yearly trend, daily for a single month). You never write a date formula; the chart re-buckets instantly. ### Cyclical buckets Below the calendar periods, a **Cyclical** section folds every date into a repeating cycle, which is exactly what you want for "when do I spend?" questions rather than "how much over time?": | Cyclical bucket | Answers | | --------------- | -------------------------------------------------------------------------------------------- | | Hour of day | Which hours see the most activity (0 to 23). | | Day of week | Which weekday you spend or earn the most. | | Month of year | Seasonality across the calendar (every January grouped together, every February, and so on). | For example, Group by Date set to **Day of week** turns a year of transactions into a seven-bar chart of spend by weekday. The Bucket by control is a segmented set of the calendar periods (Day through Year, plus Exact), with the Cyclical options (Hour of day, Day of week, Month of year) tucked into a section below it, so the whole choice lives on one popover off the date chip. ![The time channel chip in the inspector with its bucket set to Month, showing the chip's 'Group by · Date · by month' summary.](https://cdn.banksync.io/screenshots/dashboards/channel-time.a4e14eddc913c603.png "A date field bucketed by month.") ## Aggregating the value When several rows fall into the same group (all of January's transactions, say), BankSync combines them. The Value chip's **Aggregate** control chooses how. Sum, Average, and Count sit right on the control; the rest live under the Advanced section of the same chip: | Aggregate | Combines rows by | | ------------------ | --------------------------------------------------------------------------------------- | | Sum | Adding them up (total spend). | | Average | Their mean. | | Count | How many there are. | | Last | The latest value in each period (the right choice for balances; see the callout below). | | First | The earliest value in each period. | | None | One mark per row, no combining at all. | | Min / Max / Median | The smallest, largest, or middle value. | On the Value chip's popover, Sum, Average, and Count sit on a segmented control at the top, the Show amount as option follows directly beneath, and the remaining aggregates (Last, First, None, Min, Max, Median) live under the chip's Advanced section. > **Sum is not always right:** Sum is correct for flows like spending or fees, but wrong for balances. Adding Monday's balance to Tuesday's is meaningless, so BankSync defaults balance-like measures to the Last value in each period instead of summing (that is the Last aggregate in the table above, selected for you). Check the aggregate matches what the number means before trusting a total. ## Spending, income, or net This is the control a finance reader reaches for most. When the Value chip is bound to a **signed spending field** (the kind where money out is negative, like the Transactions feed's Amount), a **Show amount as** option appears on the chip and flips the sign so the chart reads naturally: - **Spending**: money out, shown as a positive number. - **Income**: money in only. - **Net**: income minus spending (the signed total). You pick the meaning; BankSync handles the math. > **Don't see Show amount as?:** 'It only shows for signed spending columns. A plain balance, an income-only column, or an amount where money out is already positive will not offer it, because the sign-flip would not mean anything for those. If the option is missing, your column simply does not need it.' ## Keep the top few categories A category with hundreds of values makes an unreadable chart. On a Group by chip, **Keep top** limits it to the largest few; a "Group the rest as Other" switch rolls everything else into a single "Other" slice. So a pie of 387 merchants becomes a clean top-10-plus-Other. (This control appears on category chips, not on date or measure chips.) Both controls sit on the Group by chip's popover: a Keep top stepper for the count and, directly under it, the "Group the rest as Other" switch. ## Advanced: running totals and shares Open the **Advanced** section on the Value chip to restate the number without changing the underlying data. The **Show as** control here offers: - **None**: the value as-is. - **% of total**: each value as a share of the whole. - **Cumulative**: a running total across the groups. Advanced also holds **Number format** (currency, percent, or plain, with decimal control) and, for less common aggregates, an "Aggregate (other)" picker with Min, Max, Median, Last, and First. > **Two controls named alike:** '"Show amount as" (Spending / Income / Net, on the main chip) and the Advanced "Show as" (None / % of total / Cumulative) are two separate controls. The first decides which direction of money you are counting; the second restates that number as a share or a running total. You can use both at once.' > **If a number looks doubled:** 'If a Value chip shows an amber warning that reads "Already aggregated in Shape data," it means the field was already summarized once in the Shape data step (a query-level total) and the chart is summing it a second time. The chip offers a one-tap Set to None to stop the second pass, so the chart shows the already-summarized number as-is. Trust the warning: it is there to stop a wrong total.' ![A Value channel chip in the inspector showing the 'Already aggregated in Shape data' double-count warning, with a one-tap Set to None action to reset the aggregate.](https://cdn.banksync.io/screenshots/dashboards/channel-double-count.71adf98f21f41873.png "The double-count warning offers a one-tap Set to None fix.") ## Joining feeds and shaping data The channels cover the common case of one feed. When you need more, open **Shape data** from the Data tab. That dialog is a multi-step pipeline, kept out of the everyday channel controls so the simple path stays simple. Each step does one thing: - **Filter**: drop rows before charting (for example, only this year). - **Summarize**: group and total rows at the data level (this is the step that, if you then also aggregate on the chart, triggers the double-count warning above). - **Sort** and **Limit**: order the rows and keep the first few. - **Compute**: derive a new column with an expression. This is the one place the everyday "no formulas" rule does not apply. - **Join**: combine two feeds into one source. ![The Shape data pipeline editor as an ordered list of collapsed step cards (Filter, Compute, Summarize, Sort, Limit), each showing a one-line summary of a realistic finance transform.](https://cdn.banksync.io/screenshots/dashboards/shape-pipeline.3ac844d827b8862c.png "The Shape data pipeline: each step does one thing, top to bottom.") ## Binding into a table A Table widget binds fields as **columns** rather than axes, but the idea is the same: you choose which fields appear and how each one reads. Beyond plain text and numbers, a column can render as currency, a status pill, a progress bar, a tiny sparkline, a heat-shaded cell, a duration, a rating, a chip list, a link, and more. So your Amount column can show as money, and a category column can show as colored pills. The per-column formatting lives in the table widget's own controls; see the [KPI, table and gauge guide](/docs/dashboards/kpi-table-gauge) for how to set each column's display. ## Related guides - [The chart kind catalog](/docs/dashboards/chart-kinds): pick the kind that fits your binding. - [Filters & cross-filtering](/docs/dashboards/filters-and-cross-filtering): let viewers narrow every widget at once. - [KPI, table & gauge widgets](/docs/dashboards/kpi-table-gauge): binding specifics for the non-chart kinds. [Add dashboard filters](/docs/dashboards/filters-and-cross-filtering) --- # KPI, Table & Gauge Widgets > Configure the three non-chart widget types: a KPI big-number with comparison, target and sparkline, a richly-formatted table with per-column control, and a gauge with a needle and color bands. > Source: https://banksync.io/docs/dashboards/kpi-table-gauge Not every widget is a chart. Three widget types show numbers without an x/y plot: the **KPI** for a single headline figure, the **Table** for rows of detail, and the **Gauge** for a value against a scale. Each has its own set of controls. > **Where these controls live:** 'Each of these widgets is configured in its inspector, the panel that opens on the right when you select a widget on the canvas. To get one onto the canvas in the first place, see Adding widgets (linked at the foot of this page). To switch a widget you already have to KPI, Table or Gauge, select it and change its kind in the inspector.' ![A settled KPI widget cell on the dashboard grid: a draggable header titled Income above a large rendered figure of $12,480, with no loading spinner or truncation.](https://cdn.banksync.io/screenshots/dashboards/widget-cell.7c2ade81421397ea.png "A KPI widget on the canvas. Select it to open its inspector.") ## KPI: one number that matters A KPI shows a single big number (this month's spend, total balance, transaction count) with optional context around it. - **Value and summary** — Pick the field (BankSync limits the picker to measures, the numeric fields it can total), then choose how to summarize the result: Sum, Average, Median, Min, Max, Count of rows, or the latest/earliest row. - **Comparison** — Show the change against a prior period as an up/down delta, so the number has direction. Compare against the previous period, the previous year, a fixed baseline, or a rolling window. - **Sparkline** — Add a tiny inline trend line beneath the number for at-a-glance history. The KPI inspector also lets you choose a **Display as** style so the same number can read as a plain card, a change-focused delta, a progress bar toward a target, a bullet (target plus bands), or a gauge. Add a **prefix/suffix** (for example a `$` or `%`), a **label** and a **caption** (such as "vs last month"), and pick whether the number formats as a plain number, currency, percent, or a compact value with set decimals. > **Set a target for budget-vs-actual:** 'Turn on Target in the KPI inspector to set a goal value and add colored bands around it. Paired with the Progress or Bullet display style, this turns a KPI into a budget-vs-actual or goal tracker: the number shows where you are, and the bands show whether you are on track. This is the fastest way to answer "how am I doing against plan?" without building a separate chart.' ![The KPI widget inspector fully decorated: a sum of the Amount field, the comparison option enabled to show an up/down delta-arrow against a prior period, and the sparkline toggle turned on to add an inline area trend line beneath the number.](https://cdn.banksync.io/screenshots/dashboards/kpi-inspector.5bdeea912beded3c.png "KPI inspector with the sum value, comparison delta and sparkline enabled. Target and Display-as controls live in the same panel.") ### Worked example: spend this month, vs last month 1. Add a KPI widget and select it to open the inspector. 2. Under **Value**, pick your amount field and set **Summarize** to **Sum**. 3. Turn on **Comparison** and set **Compare against** to **Previous period**, so the delta reads "vs last month". 4. Optionally turn on **Sparkline** for a small trend line, and add the caption "vs last month". You now have a single headline number with direction, no chart required. ## Table: rows with per-column control A Table widget lists rows from your data with control over each column. **Shape a table** 1. **Choose and order columns** — Show the fields you want and drag to reorder them; remove the ones you do not need. 2. **Set how each column reads** — Open a column and pick its Format. The choices are Text, Number, Currency (with a currency picker), Percent, Date, Relative date, Yes/No, Duration, and JSON. BankSync picks a sensible default from the data, and you can override it per column. 3. **Align, pin and size** — Per column you can set the alignment (left/right/center), pin it to the left or right edge so it stays in view as you scroll sideways, set a fixed width, and toggle whether the column is sortable. 4. **Rename and pick an icon** — Give the widget a clear title and icon so it is easy to find. Beyond the per-column format, the **Appearance** section sets the look of the whole table: row density (comfortable/compact/tight), borders, zebra stripes, row numbers, a sticky header, a sticky first column, and whether long text wraps. ![The table widget inspector's column manager: a Date column card and an Amount column card, each with a reorder grip and per-column format, alignment and pin controls, plus two more fields available to add to the table.](https://cdn.banksync.io/screenshots/dashboards/table-inspector.354ae711218831ee.png "Table inspector column manager: reorder, format, align and pin each column") > **Rich cell formats render automatically:** 'Tables can show far more than plain text and numbers. Depending on the data, a cell can render as a status pill, a progress bar, an inline sparkline, heatmap-shaded shading, a star rating, tag chips, a link, an image, formatted Markdown, a range bar, a difference indicator, an icon, or a duration. These richer formats are assigned automatically from the shape of your data; the per-column Format dropdown covers the everyday choices (currency, percent, date, duration, and so on).' ![A rendered table showing several rich cell formats at once: a currency column with signed amounts that tint by sign (Woolworths minus $412.18, salary plus $6,540.00), a status column with Posted, Pending and Cleared pills, a budget-used percentage column, and a 4-week trend sparkline column, with a 142 rows meta line beneath.](https://cdn.banksync.io/screenshots/dashboards/data-preview.2083d5619b34503f.png "A table renders status pills, sign-tinted currency, percent and an inline trend, all chosen automatically from the data.") > **How coloring works:** 'Several formats color themselves from the data: currency and percent cells tint by sign (so negatives stand out), and status cells take a tone from their value. You do not author per-cell rules in the inspector; pick the format that matches the column and the coloring follows the data as it updates.' ### Pagination Long results stay readable because the table paginates. The **Pagination** section lets you choose the mode: **Paged** (the usual default, with page controls), **Virtual** (smooth scroll through a long list), or **None**. When pagination is on, set the rows per page (default 25). Pagination is a setting you can change, not something fixed. ## Gauge: a value on a scale A Gauge draws a needle on a banded arc, good for a value measured against a target or a healthy range. - **Value** — Type or pick the result value the needle points to. This is a free-text box with suggestions, not a field dropdown, and the gauge sums the rows for you (there is no separate aggregate choice). - **Scale** — Set the min and max, the arc shape (half, three-quarter, full), and thickness. - **Bands** — Add colored bands (for example green, amber, red) so the reading has meaning at a glance. ![The gauge widget inspector for a savings-rate goal: a three-quarter arc shape, a percent unit, and green/amber/red color bands so the needle's position reads as a status against the scale.](https://cdn.banksync.io/screenshots/dashboards/gauge-inspector.f1cbe3981117d6d1.png "Gauge inspector for a savings-rate goal: three-quarter arc, percent unit, green/amber/red bands") > **Gauge bands:** A gauge with no bands draws its arc in one accent color. Add bands to turn it into a status dial, where each range gets its own color and the needle's band tells the story. ### Worked example: savings rate against a 70% target 1. Add a Gauge widget and select it to open the inspector. 2. Under **Value**, type the alias of your savings-rate result (the suggestions list helps); the gauge sums the rows to a single figure. 3. Set the **Scale** min to 0 and max to 100, with a percent unit. 4. Add three **Bands**: red up to 50, amber up to 70, green beyond 70. The needle now lands in the band that matches your savings rate, so the reading is a status, not just a number. ## Related guides - [Binding data](/docs/dashboards/binding-data): the Value and summarize controls these widgets share with charts. - [The chart kind catalog](/docs/dashboards/chart-kinds): the plotted chart kinds. - [Adding widgets](/docs/dashboards/adding-widgets): add a KPI, table, or gauge from the library. [Add dashboard filters](/docs/dashboards/filters-and-cross-filtering) --- # Dashboard Filters & Cross-Filtering > Add dashboard-wide controls like a date range so every widget narrows at once, choose where the filter applies, lock data per viewer, and wire a chart click to cross-filter the rest. > Source: https://banksync.io/docs/dashboards/filters-and-cross-filtering A dashboard filter is a control that narrows every widget at once: pick a date range, a category, or an account, and the whole dashboard responds. By default a filter is applied where the data is read, so the numbers stay correct, not just hidden on the screen (you can change where a filter applies, and you can lock data per viewer; both are covered below). [![Authoring dashboard filters from the editor: opening the Filters side panel, binding date and category controls to real transaction fields, and watching the dashboard widgets respond together.](https://cdn.banksync.io/videos/filters-cross-filtering.poster.425fe166dd241bc5.png)](https://cdn.banksync.io/videos/filters-cross-filtering.df8be41b59c2e173.mp4) [Watch: Authoring dashboard filters from the editor: opening the Filters side panel, binding date and category controls to real transaction fields, and watching the dashboard widgets respond together.](https://cdn.banksync.io/videos/filters-cross-filtering.df8be41b59c2e173.mp4) ![The dashboard Filters panel in full authoring mode: each row has an editable label, control type, target column, operator and apply-plane selects; one row shows a 'Compare to' not-applied warning because it has no target column, and a locked row is a row-level security filter.](https://cdn.banksync.io/screenshots/dashboards/filters-panel.64618620c58462e7.png "The Filters panel in authoring mode. Each row carries the label, control type, target column, operator, and where it applies; the locked row is a row-level security filter, and the warning row has no target column yet.") ## Adding a filter Open the **Filters** panel and add a filter. You choose the **column** it targets from your feed's fields (the picker offers real columns, so there is nothing to type or spell wrong) and the control type that fits it. **Author a filter** 1. **Open Filters** — Open the Filters panel from the dashboard toolbar. 2. **Pick a target column** — Choose the field to filter on from the list of your feed's columns. This step is not optional: a filter with no target column does nothing (more on that below). 3. **Choose a control type** — Pick how viewers set it (a date range, a dropdown, a search box, a slider). 4. **Choose an operator** — Decide how the value is matched. Each control type starts on a sensible default (a text search defaults to "contains", a date or number range to "between", a multi-select to "is any of"), and you can change it in the row's operator select (for a text column you can switch between contains, starts with, or exactly equals). 5. **Choose where it applies** — Pick the apply plane (see "Where a filter is applied" below). The default is fine for almost everyone. 6. **Set a default** — Optionally set a default value so the dashboard opens pre-filtered, and pin the control to the header bar if you want it always visible. > **A filter with no target column does nothing:** This is the most common first mistake: you add a filter, pick a control type, set a value, and nothing narrows. The cause is almost always a missing target column. A filter that carries a value but is not pointed at a field is inert, so the panel flags it with a 'not applied' warning. If a control on your dashboard does nothing, open Filters and check that its target column is set. > **Worked example: a pinned Last-90-days date filter:** Open Filters and add a filter. Set the target column to Date. Choose the Date range control type (the operator is 'between' by default, which is what you want). Set the default to the Last 90 days preset so the dashboard opens already scoped to the recent quarter. Turn on Pinned so the control sits in the header bar above every widget. Now every widget that has a Date column narrows to the last 90 days the moment the dashboard loads, and a viewer can widen or shift the window from the header. ## Control types - **Date range** — Pick a from/to range, with quick presets. The most common filter. - **Single-select** — Pick exactly one value. Renders as a row of segmented buttons, so the choices are all visible at once. - **Multi-select** — Pick several values at once. Renders as a checkbox dropdown, better for long option lists. - **Search** — Type to match a text column. Defaults to "contains" matching; you can switch it to "starts with" or "exactly equals". - **Number range** — A slider for an amount or numeric range. - **Toggle** — An on/off switch for a yes/no column. - **Static or live options** — Pick from a fixed list you define, or let the options fill in from the data. > **Set the slider bounds on a Number range:** 'A Number range control needs a minimum and a maximum to know where its slider starts and stops. If you do not set them, it falls back to 0 to 100, which will not reach larger dollar amounts. When you add a Number range filter, set its min and max to span the values you actually want to filter (for example 0 to 50,000 for transaction amounts).' ![A date-range filter control showing a committed preset of 90 days from 2026-01-01 to 2026-05-31, with quick presets.](https://cdn.banksync.io/screenshots/dashboards/filter-date-range.2df8de4db810be98.png "A date-range control, the most common dashboard filter.") ![A multi-select filter control with a resolved Category option list and two values picked, Food & drink and Travel.](https://cdn.banksync.io/screenshots/dashboards/filter-multi-select.3a1e29e9c74e5af1.png "A multi-select control for picking several values at once.") A Number range filter renders as a slider with a draggable low and high handle, so a viewer drags the band to set, for example, a minimum and maximum transaction amount. A Toggle filter renders as a single on/off switch for a yes/no column. ## Pinned filters vs filter widgets A filter can live in two places. A **pinned** filter shows in the dashboard's header bar, always visible above the widgets. Alternatively, you can add a **filter control widget** that sits on the grid like any other widget, handy for laying controls out alongside the charts they affect. Both drive the same dashboard filter: a control widget is just a second face for a filter you already authored, bound to it by its id, so changing either one moves the same value. When you add a filter control widget to the grid, its inspector binds the widget to an existing dashboard filter by that filter's id, which is how the two faces stay in sync: change the value on either the pinned header control or the on-grid widget and the shared filter moves. ## Where a filter is applied Every filter is applied in one of two places, and the Filters panel lets you choose per filter: - **At the source (server)** — The data is read with the filter already applied, so aggregates recompute and viewers cannot bypass it. This is the default, and it is required for the row-level security filters described below. - **In the browser (client)** — The filter is applied after the data is fetched, which feels instant and is captured in the page URL. Best for quick, low-sensitivity narrowing where re-reading from the source would be overkill. Unless you change it, a filter is set to apply at the source. That is the safe choice, and it is why the numbers stay correct (see the callout below). You only need the browser plane when you want the snappiest possible response on a non-sensitive filter. > **Source-applied filters keep aggregates correct:** 'A filter applied at the source is applied by the server when it reads your data, not by hiding rows in the browser. That means an aggregated number (a sum, an average) recomputes for the filtered set, so a filtered total is actually correct, not a partial view of an unfiltered total. A browser-applied (client) filter narrows what is already on screen instead, which is why source-applied is the default and the only option for security filters.' ## Lock data per viewer (row-level security) A filter can be a **row-level security filter**: instead of letting the viewer choose a value, it binds to who the viewer is and locks the data to them. For example, a filter on `portal_client_id` can pin a shared client portal so each client only ever sees their own rows. Security filters behave differently from ordinary filters on purpose: - They are always applied at the source, so they cannot be bypassed. - A viewer cannot remove, change, or widen them, and they show as **locked** in the Filters panel (that is the locked row in the screenshot above). - They bind to an identity claim (such as the signed-in member or the portal client) read from the verified session or embed token, not to a value the viewer types. - They fail closed: if one is misconfigured, the dashboard returns no rows rather than leaking everything. A published snapshot will not even mint with a live security filter unless the data was already pre-filtered when it was published. Use a security filter whenever the same dashboard is shared with multiple people who must each see only their own slice. For everyday narrowing, the ordinary control types above are what you want. ## Cross-filtering: click a bar to focus Cross-filtering lets a click on a chart narrow the rest of the dashboard: click a bar and every other widget refocuses on that value. It is powerful, but unlike the controls above it is **not** automatic. An author has to turn it on for a specific chart, and there are a few limits worth knowing before you rely on it. - **It has to be wired up per chart.** A chart does nothing on click until cross-filtering is enabled on it and pointed at which dashboard filter to drive and which field's value to send. There is no point-and-click toggle for this in the app yet; it is set on the widget's configuration (today via the widget spec or an AI agent through MCP), so most charts will simply not respond to clicks until someone sets it up. - **Bar and column charts only, for now.** Clicking emits a value only from bar and column charts. Pie and donut slices, lines, and other kinds do not emit a cross-filter yet, even when cross-filtering is enabled, so "click a slice" will not work. - **Clicking does not toggle off.** A click sets the filter to the clicked value; clicking the same bar again just re-sets the same value rather than clearing it. To clear a cross-filter, clear the underlying filter from its control (for example reset the pinned filter in the header). When it is set up, cross-filtering is a fast way to drill in: on a spending-by-category bar chart with cross-filtering enabled, clicking the "Travel" bar narrows every other widget on the dashboard to Travel, so a single click answers "what does the rest of the picture look like for just this category?". ![The widget inspector Advanced tab for a Merchant spend bar widget, showing the cross-filter interactions block with crossFilter set to true, emitting a merchant filter on click and affecting two peer widgets, above the raw spec editor.](https://cdn.banksync.io/screenshots/dashboards/advanced-tab.4e553557fb8b69c7.png "Cross-filtering is wired on the widget's Advanced tab: enable crossFilter, choose the merchant value to emit on click, and the peer widgets it drives.") > **Removing a filter:** 'Removing a dashboard filter also unlinks any filter control widget bound to it, so you will not be left with a control that points at nothing.' > **A filtered view is shareable:** 'The filter and cross-filter state you set while viewing a dashboard is captured in the page URL, so a filtered view survives a refresh and can be bookmarked or sent as a link. Send someone the URL after you have narrowed to last quarter and one category, and they open the dashboard already scoped the same way. (Row-level security filters are the exception: they are applied per viewer at the source, so the link never widens what someone is allowed to see.)' ## Related guides - [Binding data](/docs/dashboards/binding-data): the columns a filter can target come from the widget's feed. - [Adding widgets](/docs/dashboards/adding-widgets): add a filter control as a widget. - [Publishing & sharing](/docs/dashboards/publishing-and-sharing): filters travel with a published dashboard. [Start from a template](/docs/dashboards/dashboard-templates) --- # Dashboard Templates > Start from a prebuilt dashboard, connect it to your feeds in a couple of clicks, and save your own dashboards as reusable, shareable templates. > Source: https://banksync.io/docs/dashboards/dashboard-templates Templates are prebuilt dashboards you can start from instead of a blank canvas. A template defines the widgets and layout but leaves the data open: when you use one, you connect its widgets to **your** feeds, and it fills in with your numbers. You can also save your own dashboards as templates to reuse or share. [![Working with dashboard templates: choosing a template from the empty dashboard gallery, instantiating a normal editable dashboard, then opening Share and using Save as template for reuse.](https://cdn.banksync.io/videos/dashboard-templates.poster.12dba8b0ab0b3c4f.png)](https://cdn.banksync.io/videos/dashboard-templates.31ee290904ad7877.mp4) [Watch: Working with dashboard templates: choosing a template from the empty dashboard gallery, instantiating a normal editable dashboard, then opening Share and using Save as template for reuse.](https://cdn.banksync.io/videos/dashboard-templates.31ee290904ad7877.mp4) A couple of plain-language terms used on this page: - A **data slot** is a placeholder for a feed the template needs, for example "a transactions feed". A template lists its slots, and you fill each one with one of your feeds. - To **connect** (or "bind") a slot just means picking which of your feeds fills it. > **What's available today:** Dashboards and templates are in beta and roll out per workspace. If you don't see Dashboards or Templates in the left navigation, the feature isn't enabled for your workspace yet. Today there are two built-in starter dashboards (Spending Overview and Balance Trend) plus a few built-in starter widgets (Spend by category, Net cash flow, Balance over time), and you can save your own dashboards as templates on top of those. ## Starting from a template Open the template gallery from the empty-canvas screen or the Dashboards area. Each template card shows what it builds and whether your workspace has the feeds it needs. ![The dashboard template gallery showing template cards. Each card describes what the template builds, and some cards are marked eligible while others are flagged as blocked because the workspace is missing the feeds they require.](https://cdn.banksync.io/screenshots/dashboards/template-gallery.85b7935e184d8fca.png "The template gallery flags which prebuilt dashboards your feeds can support.") **Use a template** 1. **Pick a template** — Browse the gallery and choose one that matches what you want to track. 2. **Connect your feeds** — For each data slot the template needs, choose one of your feeds. 3. **Create the dashboard** — BankSync builds a real, editable dashboard from the template, wired to your data. 4. **Tweak it** — Edit any widget exactly as if you had built it yourself. ![The template binding dialog listing each data slot the template needs, with a single feed picker beside each slot so you can choose one of your available feeds to fill it.](https://cdn.banksync.io/screenshots/dashboards/template-binding.35e664356d727af5.png "Connect each of the template's data slots to one of your feeds.") > **Templates need the right kind of feed:** A template that charts transactions needs a transactions feed to connect to. If a required data slot has no matching feed, the gallery flags it and you'll be prompted to connect one first. Optional slots can be left empty (that part of the dashboard simply stays empty). > **One feed per slot:** 'Each slot is connected to one specific feed, not to all of your accounts at once. If you have several transactions feeds (say one per bank), the picker asks you to choose one. There\\'s no "all my accounts" option here on purpose, because connecting to a single feed is what keeps each widget editable afterward. Once the dashboard is created you can change the feed, add more widgets, or combine feeds just like any dashboard you built by hand.' ### Worked example: Spending Overview Say you want a quick monthly view of where your money goes. 1. Open the gallery and pick **Spending Overview**. 2. In the connect step, the template needs one transactions slot. Choose your **Chase Checking** transactions feed from the picker. 3. Click **Create dashboard**. BankSync mints a real dashboard with the template's widgets (for example **Spend by category** and **Net cash flow**) already filled in with your Chase Checking numbers. From there you can resize widgets, swap the feed, or add your own, exactly as if you had built it from scratch. ## Saving your own template Built a dashboard you want to reuse or share? Save it as a template. BankSync lifts your concrete feed references into open slots so the template is portable to other workspaces and feeds. (Today you save at the whole-dashboard level: there's no "save this one widget as a template" button in the app yet, even though individual widgets have their own Share tab.) ![The save-as-template dialog showing a portability blocker, warning that a widget cannot be made into an open slot and must be adjusted before the dashboard can be saved as a template.](https://cdn.banksync.io/screenshots/dashboards/save-as-template-blocked.1ad17917ab01c9d9.png "Portability checks flag any widget that cannot be made template-ready before saving.") > **Portability checks:** When you save a template, BankSync checks that every widget can be expressed without hard-coding your specific data, then tells you what to adjust before saving. Common reasons a save is blocked:A widget that reads directly from a bank or account instead of from a feed. Point it at a feed first.A widget that has fields set but no data source to connect them to.A widget using a saved query that can't be carried over to another workspace.A cross-filter that points at a filter that no longer exists. ## Sharing a template Saving a template keeps it to yourself. To let others use it, open it from **My templates** and choose **Publish**. The publish dialog lets you set: - **Visibility**, one of four levels: - **Private**, only you. - **Workspace**, anyone in this workspace. - **Public link**, anyone who has the link. - **Public**, listed in the template marketplace so others can discover it. - A **category** and up to eight **tags** (chosen from set lists, so the marketplace stays tidy). Before it lets you publish, BankSync runs the same portability check plus a safety check, and shows the result right in the dialog. If either check fails, it lists what to fix. When you publish at one of the public levels, BankSync mints a share link (a short `/t/...` URL) you can hand out. So the dialog gathers all of this in one place: the visibility level, the category and tags, the pass-or-fail portability and safety results, and (for public levels) the resulting share link. > **Share links are always real:** BankSync won't hand you a copyable link that wouldn't actually resolve. Because templates are in beta, public template links and the marketplace roll out per workspace. If public serving isn't available for your workspace yet, the dialog says so plainly instead of giving you a dead URL. ## Managing and updating Your saved templates live under **My templates**, a list showing each template's name, category, publish state, and visibility, with the Publish and state-transition actions sitting on each row. From here you can **Publish** a template (opens the share dialog above) or move it through its publish states (for example Draft to Published, or Published to Deprecated or Unlisted). There is no in-place edit or delete in this view today: to change what a template contains, save a fresh template from an updated dashboard. When a template you created a dashboard from gets a newer version, the dashboard shows a friendly **A newer version is available** banner with **Review update** and **Dismiss** actions. Reviewing builds the latest version into a brand-new draft and shows you the differences side by side. It never overwrites the dashboard you've already tweaked, so your edits are safe and you decide whether to adopt the new version. > **Build templates with an agent:** If you drive BankSync through an AI agent or the MCP tools, the agent can browse templates, check whether a template's feeds are connectable in your workspace, create a dashboard from a template, and publish a template for you. These agent tools are available in staging while the feature is in beta. ## Related guides - [Creating your first dashboard](/docs/dashboards/creating-a-dashboard): the blank-canvas alternative. - [Binding data](/docs/dashboards/binding-data): how connecting a widget to a feed works under the hood. - [Publishing & sharing](/docs/dashboards/publishing-and-sharing): publishing a finished dashboard or widget (separate from publishing a template, which is covered above). [Connect your data](/docs/dashboards/binding-data) --- # Publishing, Sharing & Embedding > Control who can see a dashboard with four visibility levels, and (where it is switched on) share a read-only link or embed a dashboard or a single widget in your own site. > Source: https://banksync.io/docs/dashboards/publishing-and-sharing Once a dashboard is in good shape, you can decide who gets to see it. You control that with four visibility levels, ranging from just you up to a public link. Where public serving has been switched on for your workspace, you can also hand out a read-only link or embed a dashboard (or a single widget) in another site. [![Publishing and sharing a dashboard: opening Share from the editor toolbar, choosing Public link visibility, saving to generate the server-issued link, then copying the share URL and embed snippet with allowed origins.](https://cdn.banksync.io/videos/publish-and-share.poster.99f8b260c790a040.png)](https://cdn.banksync.io/videos/publish-and-share.e6852cd26854ebe0.mp4) [Watch: Publishing and sharing a dashboard: opening Share from the editor toolbar, choosing Public link visibility, saving to generate the server-issued link, then copying the share URL and embed snippet with allowed origins.](https://cdn.banksync.io/videos/publish-and-share.e6852cd26854ebe0.mp4) > **Public links are still rolling out (beta):** 'Dashboards is in beta, and public link serving is being switched on workspace by workspace. Until it reaches your workspace, you can still set a dashboard to Public link or Public & indexed, but the Publish dialog will not produce a copyable link or embed code yet: it stays on a "No link yet" message. Setting visibility to Private or Workspace works today and needs no link at all. If you need to share now, the most reliable route is the Workspace level (your teammates open it in BankSync) or a template (see Related guides).' > **Save the dashboard first:** 'Sharing starts from a saved dashboard. A brand-new, unsaved draft has no Share button yet. Name the dashboard or add a widget so it saves itself, then the Share button appears in the toolbar. See Creating your first dashboard for exactly when a draft commits.' ## Share it in four steps 1. **Save the dashboard** — Give it a name or add a widget so it is saved. The Share button in the dashboard toolbar appears once there is something to share. 2. **Open Share** — Click Share in the toolbar. The window that opens is titled' ' Publish "\", so do not be thrown that it says Publish rather than Share: it is the same thing. 3. **Pick who can see it** — Choose one of the four visibility levels below (Private, Workspace, Public link, or Public & indexed). 4. **Press Save** — The confirm button is labelled Save (not Publish). Pressing it applies the visibility you chose. 5. **Copy the link, if there is one** — If public serving is live for your workspace and you chose a public level, a link and an embed snippet appear to copy. If it is not live yet, you will see "No link yet" instead (see the beta note above). ## Visibility levels Open **Share** from the dashboard toolbar and choose how widely it is visible: - **Private** — Only you can see it. This is the default for a new dashboard. - **Workspace** — Everyone in your workspace can view it. There is no link to hand out: teammates simply open it inside BankSync like any other dashboard. - **Public link** — Anyone who has the link can view it, read-only. It is not listed anywhere public, so only people you send the link to can find it. - **Public & indexed** — A public link that search engines are also allowed to list, so it can turn up in search results. > **Workspace sharing needs no link:** 'The Workspace level does not create a URL. Anyone in your workspace just opens the dashboard from the dashboards list in BankSync. There is no "workspace link" to copy, so do not go hunting for one: choosing Workspace is the whole step.' ![The Publish dialog after saving a public dashboard, showing the four visibility tiers as radio options and a server-issued share link with an iframe embed snippet, each with copy and regenerate buttons.](https://cdn.banksync.io/screenshots/dashboards/publish-dialog.27cb32827047dfae.png "The Publish dialog (opened from the Share button) once public serving is live: pick a tier, then copy the link and embed snippet.") ## Links and embedding When you set a dashboard to a public level and public serving is live for your workspace, BankSync issues the link from its server. The dialog shows two things to copy: - **One link** to the dashboard. This is the read-only URL you send to people. - **An embed snippet.** This is a short block of HTML (an `