Resources & Data Types

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.

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#

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#

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#

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#

Investments#

Investment data is split into two resources: Trades (buy/sell transactions) and Holdings (current positions). Investment data may require additional bank consent.

Trades#

Holdings#

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#

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 sixteen types, grouped by what they do — see the enrichments overview for the full map:

Key Fields#

Exactly one type-specific config block is allowed, and it must match type — sending ruleConfig on a filter enrichment is rejected.

Ruleset actions: a rule action is a discriminated union on kind — set (a static value, and the default when kind is absent), template (interpolate other fields), regexExtract (write a capture group), case (upper / lower / title) and math (abs / negate / round2). The in-app rule editor writes plain set actions; the derived kinds are API-only today. Regex patterns are safety-checked on save.

Alert destinations: email (recipients), slack (incoming-webhook URL), and webhook (URL plus optional headers). The sms shape exists in the wire format for stored legacy documents but is rejected on create and update — nothing delivers SMS yet. Slack and webhook URLs are masked in API responses (they are bearer secrets); send the masked value back unchanged to keep the stored URL.

Singleton types: memory, transfer_match and recurring are one-per-workspace and keyed deterministically, so creating one again via the API replaces the existing one rather than failing with a conflict. Every other type can have multiple instances — scope them per feed with feedIds.

Plan tiers: creating an enrichment is gated on your plan (basic / advanced / all) and returns 403 for a type the plan does not carry. The AI types additionally need the AI entitlement (Professional and above). See Changing your plan.

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#

Jobs#

A job represents a single execution of a feed sync. Jobs progress through these states:

in_progress → completed | failed | cancelled

Key Fields#

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 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.