> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dualentry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bank Connections: Inbound Feed API

> Push customer-built bank feeds into DualEntry with the V2 bank-connections API: register accounts, batch-push transactions, and unregister feeds.

Use the Bank Connections inbound API when your systems already talk to the bank and you want DualEntry to receive that feed over `/public/v2/bank-connections/`. This path is an alternative to connecting through a third-party aggregator such as Plaid, Meld, or Salt Edge. After you register a connection and push transactions, the feed appears on the [Bank Connections](https://docs.dualentry.com/accountants/core-financials/bank-connections.md) screen. An accountant then maps each account to a general ledger (GL) account and reconciles the transactions in [Bank Match](https://docs.dualentry.com/accountants/core-financials/close-management/bank-match/bank-match-ai.md), DualEntry's bank reconciliation workspace.

## What this API is

This path is a **customer-built inbound** bank feed. You **register** a connection and accounts, **push** transactions in batches while the registration is active, and **unregister** when you want DualEntry to stop accepting posts for that connection.

DualEntry does not hold an OAuth session with the bank for this source type. There is no Reconnect flow: if the feed stops, fix your push job and resume posting. On first successful registration, the connection appears on the Bank Connections screen with the `institution_name` you sent. Pass an optional `icon_url` (a direct image URL) to set the tile logo; otherwise the tile falls back to initials from the institution name. An optional `bank_url` stores the bank's public website as metadata and does not fetch a logo. This differs from [SFTP bank connections](https://docs.dualentry.com/accountants/integrations/banking-and-payments/sftp-bank-connections.md), where the Bank URL field in the app may resolve a logo from that website. An accountant can then map each of its accounts to a GL account.

## Register a connection and accounts

Create or upsert a customer API bank connection. Optionally include accounts in the same request. Stable customer keys are `connection_source_id` and each account's `account_id`. You may also send an optional `bank_url` (the bank's public website) and an optional `icon_url` (a direct logo image URL). DualEntry does not scrape a logo from `bank_url` on this API: pass `icon_url` when you want a logo; omit it to keep the initials fallback.

```bash theme={null}
curl -X POST https://api.dualentry.com/public/v2/bank-connections/ \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_source_id": "pub-reg-1",
    "institution_name": "Public API Bank",
    "bank_url": "https://www.examplebank.com",
    "icon_url": "https://www.examplebank.com/logo.png",
    "accounts": [
      {
        "account_id": "acct-pub-1",
        "account_name": "Checking"
      }
    ]
  }'
```

A successful response returns DualEntry `id` values for the connection and accounts. Keep the DualEntry account `id` for the push URL path; keep your `account_id` string for each transaction body.

## Register more accounts

Add or upsert accounts on an existing connection using the DualEntry connection id from registration.

```bash theme={null}
curl -X POST https://api.dualentry.com/public/v2/bank-connections/123/accounts/ \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      {
        "account_id": "acct-pub-2",
        "account_name": "Operating"
      }
    ]
  }'
```

## Set account status

Deactivate or reactivate accounts on a registered connection without unregistering the whole feed. Each account accepts an optional `status` of `active` or `inactive` on the accounts upsert. Use `inactive` when you want DualEntry to stop treating the account as part of the live feed.

Setting `status` to `inactive`:

* It removes the account from the Account Mapping tab.
* It unmaps the account from its GL account.

Pushing transactions to an inactive account is rejected with: `This account is inactive. Please activate the account in order to post transactions.`

Reactivating an account (`status: active`) does not restore the prior GL mapping. An accountant must map the account again from scratch.

```bash theme={null}
curl -X POST https://api.dualentry.com/public/v2/bank-connections/123/accounts/ \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      {
        "account_id": "acct-pub-2",
        "account_name": "Operating",
        "status": "inactive"
      }
    ]
  }'
```

## Push transactions

Batch upsert bank-feed rows for one DualEntry financial account. Path parameter is DualEntry's financial account id. Each item must include your customer `account_id` from registration and a unique `external_trx_id`.

```bash theme={null}
curl -X POST https://api.dualentry.com/public/v2/bank-connections/accounts/456/transactions/ \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {
        "external_trx_id": "tx-pub-1",
        "account_id": "acct-pub-1",
        "date": "2026-03-15T12:00:00+00:00",
        "amount": "12.34",
        "description": "Lunch",
        "is_posted": true,
        "counterparty": "Cafe"
      }
    ]
  }'
```

Each item in the `transactions` array accepts these fields:

| Field | Required | Notes |
| - | - | - |
| `external_trx_id` | Yes | Idempotency key; stored as `source_id` with `source_type=customer_api` |
| `account_id` | Yes | Customer account key from registration; must match the path account |
| `date` | Yes | Pending/transaction date; used when `posted_at` is null |
| `amount` | Yes | Signed decimal; see amount sign below |
| `description` | Yes | Empty string allowed |
| `is_posted` | Yes | `true` posted, `false` pending |
| `posted_at` | No | Posting date when known |
| `counterparty` | No | Payee/merchant; DualEntry maps this into Bank Match payee display |

## Handle partial batch success

One bad item does not roll back the rest of the batch. The response lists a per-item `status` of `created`, `updated`, or `error`.

```json theme={null}
{
  "success": true,
  "results": [
    {
      "external_trx_id": "ok-1",
      "status": "created",
      "id": 1001,
      "error": null
    },
    {
      "external_trx_id": "",
      "status": "error",
      "id": null,
      "error": {
        "external_trx_id": ["This field may not be blank."]
      }
    },
    {
      "external_trx_id": "ok-2",
      "status": "created",
      "id": 1002,
      "error": null
    }
  ]
}
```

Retry only the failed `external_trx_id` values. Replaying a successful id with the same payload upserts (idempotent update).

## Unregister a connection

Soft-disable a registration so further pushes and account registration are rejected. History is kept. Re-registering with the same `connection_source_id` is supported in the current release.

```bash theme={null}
curl -X DELETE https://api.dualentry.com/public/v2/bank-connections/123/ \
  -H "X-API-KEY: your_api_key_here"
```

After unregister, a push against that connection is rejected with: `Transactions cannot be posted to an inactive connection. Please re-register using the same connection_source_id before posting.` This is distinct from the account-level inactive error above: the connection message means the whole registration is disabled; the account message means only that account is inactive.

There is no Reconnect for `customer_api` feeds. If you stop pushing, DualEntry does not pull from the bank; resume by fixing your integration and posting again (or re-enable the same registration id after unregister).

## Rules and limits

Apply these contract rules when building your integration:

* **Idempotency**: Unique per organization on `external_trx_id` with `source_type=customer_api`.
* **Amount sign**: Positive = debit (money in); negative = credit (money out). Same convention as other DualEntry public bank APIs.
* **Batch size**: At most **250** transactions per push request.
* **Registrations**: Soft limit of **25** active customer API connections per organization (re-enabling an existing `connection_source_id` does not consume a new slot).
* **Start-date exclusion**: Treated like a provider feed: rows dated before the bank-match start date on the mapped GL account (the earliest date DualEntry imports feed activity for that account) are auto-excluded.
* **Backfill**: Historical loads are allowed; chunk them under the batch cap.
* **Limits are tunable**: Batch and registration caps are initial defaults and may change.

## API reference

This guide documents the bank-connections request and response shapes. Browse other V2 resources in the [V2 API reference](https://docs.dualentry.com/developers/api/resources-v2/invoices/list-invoice-records.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.