Manage a bank account

This page covers what you do after a bank account is linked. To add one, see Link and verify a bank account.

Prerequisites

A credential with payments.funding-source:read to read, and payments.funding-source:write to change or remove.
If you call with a person's login session, changes need a BankAccountChange MFA step-up. See Banking and spend.

List bank accounts

Call GET /v3/finance/external-bank-accounts. Filters:

Filter	Values
`filter[status][eq]`	`Pending`, `Verified`, `Disconnected`, `Failed`, `Removed`
`filter[capability][eq]`	`Charge` or `Payout`
`filter[verificationMethod][eq]`	`Plaid` or `MicroDeposit`
`filter[subjectType][eq]` and `filter[subjectId][eq]`	Send both together. `subjectType` is `Account`, `Payee`, or `Payer`.

Sending only one of subjectType and subjectId also returns 422.

curl "https://api.wingspan.app/v3/finance/external-bank-accounts?filter[status][eq]=Verified&filter[capability][eq]=Payout" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

Read one with GET /v3/finance/external-bank-accounts/{bankAccountId}. Account numbers are never returned. You get accountNumberMask, the last digits.

Update a bank account

Call PATCH /v3/finance/external-bank-accounts/{bankAccountId}. Send only what changes.

Field	Notes
`nickname`	A label
`isDefault`	Make it your default account
`accountHolderType`	`Individual` or `Business`. Sets the ACH code Wingspan uses.
`verificationMethod`	Only `MicroDeposit`. Starts micro-deposit verification on a manually entered account.
`integration.quickbooks`	`assetId`, `expenseId`, `liabilityId`, and `bankAccountId` map the account to QuickBooks accounts. Send `null` for one to clear it.

curl -X PATCH "https://api.wingspan.app/v3/finance/external-bank-accounts/Ba7Hn2Qx5Rt8Kw3Lp6Zb9D" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "nickname": "Payroll funding", "isDefault": true }'

Send only the editable fields; metadata returns 422.

Check a balance

Call GET /v3/finance/external-bank-accounts/{bankAccountId}/balance. The response has balance, available, hold, pending, currency, and updatedAt. The call returns 409 when the request conflicts with the account's current state.

List the account's transactions

Call GET /v3/finance/external-bank-accounts/{bankAccountId}/transactions for transactions synced from the bank.

filter[startDate][eq] and filter[endDate][eq] take YYYY-MM-DD.
sort[effectiveAt] or sort[date], asc or desc. Only one sort field is allowed.
Each entry has amount, direction (Credit or Debit), status, description, balance, and effectiveAt.

To pull the latest transactions from every linked bank into your bookkeeping, see Transactions and categories.

Reconnect a disconnected account

When a linked account's status is Disconnected, the bank login needs repair. Call POST /v3/finance/external-bank-accounts/{bankAccountId}/reconnect. The body is optional and takes redirectUri. The response is 200 with a new linkToken and expiresAt. Open the bank-linking flow with it so the account holder can sign in again. The token doesn't expose stored credentials.

Find out what's missing

Call GET /v3/finance/external-bank-accounts/{bankAccountId}/missing-fields. The response lists requiredFields and requiredDocuments still needed to finish setting up the account. Both are empty when nothing is missing.

Remove a bank account

Call DELETE /v3/finance/external-bank-accounts/{bankAccountId}. The response is 204 with no body. A 409 means the account can't be removed in its current state.

Errors

Status	Meaning
`403`	Missing scope, or `StepUpMfaRequired`
`404`	The bank account doesn't exist or isn't yours
`409`	The request conflicts with the account's current state
`422`	A filter or field isn't valid. This includes `externalId`, a lone `subjectType` or `subjectId`, an unknown `status`, `verificationMethod`, or `capability` value, a date that isn't `YYYY-MM-DD`, and `metadata`.