--- title: "Resources & Data Types" description: "Understand the BankSync data model: banks, accounts, transactions, balances, investments, loans, enrichments, feeds, jobs, and more." section: "API" canonical: "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 sixteen types, grouped by what they do — see the [enrichments overview](/docs/enrichments/enrichments-overview) for the full map: | Group | `type` values | | -------------- | ---------------------------------------------------------------------- | | Transform data | `rule`, `lookup` | | Guard data | `filter`, `split`, `transfer_match`, `dedupe` | | Watch | `alert`, `monitor`, `budget`, `recurring`, `fees`, `anomaly`, `digest` | | AI & learning | `memory`, `ai_categorize`, `ai_merchant` | ### Key Fields | Field | Description | | --------------------- | --------------------------------------------------------------- | | `id` | Enrichment ID | | `name` | Display name | | `type` | One of the sixteen values above | | `enabled` | Active toggle | | `dataType` | transactions, balances, etc. (inert for workspace-scoped types) | | `feedIds` | Scoped feeds | | `allFeeds` | Apply to all feeds | | `order` | Position within the enrichment's pipeline stage | | `ruleConfig` | Rules: conditions + actions | | `alertConfig` | Alerts: conditions + destinations | | `memoryConfig` | Memory: pattern + target fields | | `lookupConfig` | Lookup Table: match field, match mode, target field, entries | | `filterConfig` | Filter: conditions to exclude on | | `splitConfig` | Split: conditions + the lines to split into | | `transferMatchConfig` | Transfer Matcher: window + tag/suppress action | | `dedupeConfig` | Duplicate Screen: window + flag/suppress action | | `monitorConfig` | Feed Monitor: stale-sync + no-records checks, destinations | | `budgetConfig` | Budget: dimension, metric, window, threshold, direction | | `recurringConfig` | Recurring Registry: price-increase, new, missed-charge checks | | `feesConfig` | Fee Ledger: creep threshold + destinations | | `anomalyConfig` | Anomaly Detector: new-merchant, spike, velocity checks | | `digestConfig` | Digest: cadence, hour (UTC), tone, destinations | | `aiCategorizeConfig` | AI Categorizer: target field, taxonomy, confidence threshold | | `aiMerchantConfig` | Merchant Cleanup: options (no required configuration) | 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](/docs/account-billing/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 | 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.