Plaid actions

The Plaid block, shown in Studio as Finances (Plaid), reads institutions, accounts, balances and transactions from bank and credit-card accounts linked through Plaid. For the plain-language overview, see Bank and card accounts (Plaid).

When to use it

Use syncTransactions on a schedule to keep a Data Table of bank and card transactions for reconciliation. Use listTransactions for a one-off date range, and getBalances for a balance check.

Connection

Actions

The action id is plaid.<action>. All five are in the Studio Action list.

Fields

Output

Every action returns the same envelope. Collections an action does not use are empty and objects are null.

A later step loops over {{steps.<id>.transactions}} and should key on eventId, which is stable for each version of a transaction.

How the sync works

syncTransactions keeps a cursor per workflow, step, connection and account; you cannot set it. For each account it reads every page of changes, then in one database transaction stores the changes, upserts the rows into the Data Table by eventId and advances the cursor. If two runs overlap, the later one restarts from the cursor the first one saved. Filters decide only what the step emits; the Data Table receives every change.

The destination Data Table must already have these columns: eventId, connectionId, accountId, providerTransactionId, changeType, versionHash, status, postedDate, authorizedDate, amount, absoluteAmount, currency, direction, description, merchant, reference, category, pendingTransactionId, accountName, accountMask, reconciliationStatus, processedAt, lastError. The step checks them, and the table's row limit, before calling Plaid.

Example

{
  "id": "sync_bank",
  "type": "action",
  "name": "Sync operating account transactions",
  "action": "plaid.syncTransactions",
  "config": {
    "operation": "syncTransactions",
    "connection": "<plaid-connection-id>",
    "accountIds": ["<account-id>"],
    "destinationTableId": "<data-table-id>",
    "changeTypes": ["added", "modified", "removed"],
    "dateMode": "none",
    "status": "all",
    "direction": "all"
  }
}

Live catalog

GET /api/v1/blocks/plaid returns the fields and the five actions. See Block and action discovery.

Errors and limits

• Financial Accounts steps require an explicit institution connection: pin config.connection.
• requires accountIds: select at least one account on the step: an empty selection would read nothing, so the step fails instead.
• DESTINATION_COLUMNS_MISSING, DESTINATION_COLUMNS_AMBIGUOUS, DESTINATION_TABLE_FULL: fix the Data Table and re-run. Nothing was synced and the cursor did not move.
• listTransactions rejects dateField: "authorized", because Plaid's historical read filters on posted date only.
• When the institution needs the user to sign in again, the step fails and the connection shows Requires action in Integrations.