Plaid API Integration Guide
A developer reference for integrating Plaid's financial data APIs. Covers the Link initialization flow, product APIs (Transactions, Auth, Identity, Assets, Investments, Liabilities), Item lifecycle management, webhook handling, and Plaid Exchange.
Link Flow
Plaid Link is the client-side component that handles institutional authentication. The integration flow has three steps:
- Create a Link token: Call
POST /link/token/createfrom your server with the products you need, the user's client_user_id, country codes, and language. The response includes a temporarylink_token. - Initialize Link: Pass the link_token to the Plaid Link SDK on the client. The user selects their institution, enters credentials, and completes any MFA challenges within the Plaid-hosted UI.
- Exchange public token: On success, Link returns a temporary
public_token. Exchange it server-side viaPOST /item/public_token/exchangeto obtain a persistentaccess_tokenanditem_id.
The access_token is long-lived and should be stored securely. Each access_token corresponds to one Item (a single connection between a user and an institution).
Products
Plaid offers product-specific APIs, each enabled per Item at Link initialization time. Additional products can be added to an existing Item without re-authenticating the user.
| Product | Description | Refresh Rate | Common Use Cases |
|---|---|---|---|
| Transactions | Access up to 24 months of categorized transaction history. Supports real-time updates via webhooks. | Daily automatic refresh; on-demand via /transactions/refresh | Personal finance, expense tracking, underwriting |
| Auth | Retrieve bank account and routing numbers for ACH payments. Instant verification with micro-deposits fallback. | On-demand | ACH payment initiation, direct deposit switching |
| Identity | Fetch account holder name, address, phone, and email directly from the financial institution. | On-demand | KYC verification, fraud prevention, account ownership confirmation |
| Assets | Generate a standardized Asset Report with account balances and transaction history across multiple Items. | Point-in-time snapshot; refreshable via /asset_report/refresh | Mortgage origination, loan underwriting, tenant screening |
| Investments | Access brokerage and retirement account holdings, transactions, and securities information. | Daily automatic refresh | Wealth management, portfolio tracking, tax lot reporting |
| Liabilities | Retrieve loan details including balances, payment schedules, interest rates, and student loan servicer data. | Daily automatic refresh | Debt consolidation, student loan refinancing, credit analysis |
| Balance | Fetch real-time and available balances for all linked accounts. | On-demand (real-time with supported institutions) | Insufficient funds checks, balance verification before transfers |
| Income | Verify employment and income from payroll providers via bank statements or direct employer connections. | On-demand | Lending decisions, income verification, gig worker assessment |
Item Lifecycle
An Item can transition between several states. When a user's credentials change or an institution requires re-authentication, the Item enters an error state with code ITEM_LOGIN_REQUIRED. Resolve this by launching Link in update mode with a new link_token generated using access_token in the request body.
Remove Items via POST /item/remove. This revokes the access_token and deletes the connection. Items that remain in an error state for 7 days without user action may stop receiving data refreshes.
Webhook Handling
Plaid sends webhooks to the URL specified in the link_token or configured at the Item level. Key webhook types include:
TRANSACTIONS: INITIAL_UPDATE-- Initial transaction pull is complete (typically 0-30 seconds after linking)TRANSACTIONS: HISTORICAL_UPDATE-- Historical backfill complete (up to 24 months, may take minutes)TRANSACTIONS: SYNC_UPDATES_AVAILABLE-- New transactions available for syncITEM: ERROR-- Item entered an error state requiring user actionITEM: PENDING_EXPIRATION-- Access consent is about to expire (7 days notice)
Plaid signs webhooks with a JWK (JSON Web Key). Verify the JWT in the Plaid-Verification header against the public keys at /webhook_verification_key/get. Cache the key and re-fetch only when verification fails.
Plaid Exchange
Plaid Exchange allows financial institutions to share data directly with Plaid via API, replacing screen scraping. For developers, Exchange connections are transparent -- data from Exchange-enabled institutions arrives through the same product APIs. The key benefit is higher reliability, faster data refresh, and better data quality compared to credential-based connections.
Error Handling Patterns
Plaid API errors return a structured JSON body with error_type, error_code, error_message, and display_message (safe to show to users).
- ITEM_ERROR: Issues with a specific Item (login required, institution not responding). Retry with backoff or prompt user re-authentication.
- API_ERROR: Server-side issues at Plaid. Safe to retry with exponential backoff.
- INVALID_REQUEST: Malformed request parameters. Fix the request before retrying.
- RATE_LIMIT_EXCEEDED: Too many requests. Back off and retry after the window resets.
- INSTITUTION_ERROR: The financial institution is unavailable. Retry later; these are typically transient.
Disclaimer: This guide is an independent technical reference and is not affiliated with or endorsed by Plaid Inc. API specifications and product availability are subject to change. Always consult the official Plaid documentation for the most current information.