🔗 Bank Accounts & Linking

Connect insured bank accounts for direct debits. Use the Audit1 Bank Linking widget for instant, verified bank connections or add accounts manually.

Embedded Bank Linking (Recommended)

Embed Audit1's bank linking widget in your UI. The insured selects their bank, authenticates, and you get verified account details — no manual entry needed. Supports 10,000+ financial institutions.

Step 1: Create a Link Token

POST /api/v1/plaid/link-token

curl -X POST /api/v1/plaid/link-token \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -d '{ "user_id": "your_internal_user_id" }'

{
  "ok": true,
  "data": {
    "link_token": "link-sandbox-12345-abcde..."
  }
}

Step 2: Open the Bank Linking Widget in Your Frontend

// Install: npm install react-plaid-link
import { usePlaidLink } from "react-plaid-link";

const { open } = usePlaidLink({
  token: linkToken,  // from Step 1
  onSuccess: (publicToken, metadata) => {
    // Send publicToken to your backend
    exchangeToken(publicToken, metadata);
  },
});

open();

📘

See the Plaid Link documentation for full frontend integration details and supported frameworks.

Step 3: Exchange the Public Token

POST /api/v1/plaid/exchange

curl -X POST /api/v1/plaid/exchange \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -d '{
    "public_token": "public-sandbox-12345-abcde...",
    "user_id": "your_internal_user_id",
    "employer_id": "681xyz789abc123456789012"
  }'

This creates a permanent connection and automatically syncs the insured's bank accounts.

Step 4: Create a Debit Account from the Linked Bank

POST /api/v1/bank-accounts/ach/from-plaid

curl -X POST /api/v1/bank-accounts/ach/from-plaid \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -d '{
    "owner_type": "employer",
    "owner_id": "681xyz789abc123456789012",
    "plaid_account_id": "acct_123...",
    "plaid_item_id": "item_456...",
    "nickname": "Operating Account",
    "is_primary": true
  }'

The debit account is pre-verified (no micro-deposits needed) because credentials come directly from the linked bank.

Manual Bank Account Entry

For insureds who prefer not to use the bank linking widget.

Create a Debit Account

POST /api/v1/bank-accounts/ach

curl -X POST /api/v1/bank-accounts/ach \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -d '{
    "owner_type": "employer",
    "owner_id": "681xyz789abc123456789012",
    "routing_number": "021000021",
    "account_number": "1234567890",
    "bank_name": "Chase",
    "account_type": "checking",
    "nickname": "Payroll Account"
  }'

{
  "ok": true,
  "data": {
    "_id": "684abc123def456789012345",
    "account_last4": "7890",
    "routing_last4": "0021",
    "status": "unverified",
    "bank_name": "Chase",
    "account_type": "checking"
  }
}

Note: Manually-entered accounts start as unverified. Full routing and account numbers are never returned in API responses — only the last 4 digits are shown.

Bank Account Management

List Bank Accounts

GET /api/v1/bank-accounts?employer_id=...&connection_type=plaid&status=active

Get a Bank Account

GET /api/v1/bank-accounts/{id}

Update a Bank Account

PATCH /api/v1/bank-accounts/{id}

Set as Primary Account

PATCH /api/v1/bank-accounts/{id}/default

{ "primary": true }

Delete a Bank Account

DELETE /api/v1/bank-accounts/{id}

Bank Connections & Transactions

List Connections

GET /api/v1/plaid/connections?employer_id=...&status=active

Get Live Balances

POST /api/v1/plaid/balance

{ "plaid_item_id": "item_456..." }

View Bank Transactions

GET /api/v1/plaid/transactions?employer_id=...&date_from=2026-01-01&date_to=2026-03-31

Transaction Summary

GET /api/v1/plaid/transactions/summary?employer_id=...&date_from=2026-01-01

{
  "ok": true,
  "data": {
    "total_transactions": 847,
    "total_debits_cents": 12500000,
    "total_credits_cents": 15200000,
    "net_cents": 2700000
  }
}

Security

• Routing and account numbers are encrypted at rest using envelope encryption (AES-256-GCM)
• Credentials are never returned in API responses — only last 4 digits
• All bank operations are logged without sensitive data
• Bank linking connections are encrypted before storage