A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Plaid API is how an app or AI agent connects to a person's bank to read transactions, pull account and routing numbers, check balances, fetch identity, or read investments, liabilities, and income. Access is granted through a client_id and secret, plus an access token for the connected bank, and each product like Auth or Transactions must be enabled and consented to before its endpoints return anything. Plaid pins the API to a dated version and pushes events to a webhook when data changes.
How an app or AI agent connects to Plaid determines what it can reach. A call is made against a Plaid environment with a client_id and secret, an access token names which connected bank Item it acts on, and Plaid pushes events to a registered webhook. A hosted server also exposes Plaid dashboard tools to agents.
The REST API takes JSON request bodies over HTTPS and returns JSON. Every endpoint is a POST, called against a Plaid environment at https://sandbox.plaid.com or https://production.plaid.com. A call carries a client_id and secret, and most calls also carry an access_token naming the connected Item to act on. The Plaid-Version header pins the dated API version.
Plaid POSTs a JSON webhook to the URL registered on an Item when data changes or an asynchronous job finishes. Each carries a webhook_type and webhook_code. The receiver verifies the Plaid-Verification header, a JWT signed with ES256, by fetching the public key from /webhook_verification_key/get, checking the request_body_sha256 claim against the raw body, and rejecting anything older than 5 minutes.
A hosted Model Context Protocol server at https://api.dashboard.plaid.com/mcp/ exposes Plaid dashboard tools to AI agents, for debugging Items, reviewing Link conversion analytics, and checking usage metrics. It authenticates with an OAuth token carrying the mcp:dashboard scope, obtained through the client_credentials grant. Plaid notes the server is under active development with limited support, so it is not yet a stable interface.
Almost every Plaid endpoint authenticates with a client_id and a secret, sent in the JSON request body or in the PLAID-CLIENT-ID and PLAID-SECRET headers. The secret is specific to one environment, either Sandbox or Production, so the same call runs against simulated or live data depending on which secret is used. There are no OAuth scopes on first-party calls; what a call can reach is set by the products enabled on the Item, not by the credential.
Most product endpoints also require an access_token, returned by /item/public_token/exchange after a user connects a bank through Link. The token represents one connected Item and names which accounts and products a call acts on. It can be rotated with /item/access_token/invalidate and revoked by removing the Item.
The hosted Dashboard MCP server uses an OAuth token rather than the client_id and secret. The token is minted through the client_credentials grant at the OAuth token endpoint, carries the mcp:dashboard scope, and expires after 15 minutes, with a refresh token to renew it.
The Plaid API is split into products an agent can act on, like Transactions, Auth, Identity, Investments, Liabilities, and Income. Each product must be enabled on an Item and consented to by the account holder before its endpoints return data, so what an agent can reach depends on which products are turned on, not on a token scope.
Methods for starting a Link session and minting the tokens that connect a bank.
Methods for exchanging tokens and managing a connected bank Item.
Methods for listing accounts on an Item and reading balances.
Methods for reading transaction history and recurring streams.
Methods for reading bank account and routing numbers for money movement.
Methods for reading account-holder identity and matching it against supplied data.
Methods for reading investment holdings and investment transactions.
Methods for reading loan and credit-account liability data.
Methods for creating a user and reading bank and payroll income.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Link & tokensMethods for starting a Link session and minting the tokens that connect a bank.2 | ||||||
| POST | /link/token/create | Create a short-lived link_token to initialize a Link session, naming the products the Item must support. | write | Link | Current | |
The products array set here decides which product endpoints the resulting Item can call. Acts onlink_token Permission (capability) LinkVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /link/token/get | Retrieve a Link session's metadata, including callbacks fired and the public_token. | read | Link | Current | |
Used by Hosted Link and Multi-Item Link, where tokens are not returned via a front-end callback. Acts onlink_token Permission (capability) LinkVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ItemsMethods for exchanging tokens and managing a connected bank Item.5 | ||||||
| POST | /item/public_token/exchange | Exchange a public_token from Link for a persistent access_token tied to the Item. | write | Items | Current | |
The access_token returned here is required by every product endpoint that acts on the Item. Acts onaccess_token Permission (capability) ItemsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /item/get | Retrieve an Item, including its status, enabled products, and any error. | read | Items | Current | |
Read-only. Acts onitem Permission (capability) ItemsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /item/remove | Remove an Item and invalidate its access_token and all associated tokens. | write | Items | Current | |
Irreversible for that connection; required to stop billing on the Item. Acts onitem Permission (capability) ItemsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /item/webhook/update | Update the webhook URL associated with an Item. | write | Items | Current | |
Plaid sends a WEBHOOK_UPDATE_ACKNOWLEDGED webhook to the new URL on success. Acts onitem Permission (capability) ItemsVersionAvailable since the API’s base version Webhook event item-webhook-update-acknowledgedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /item/access_token/invalidate | Rotate an Item's access_token, issuing a new one and immediately invalidating the old one. | write | Items | Current | |
Used for credential rotation after a suspected leak. Acts onaccess_token Permission (capability) ItemsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountsMethods for listing accounts on an Item and reading balances.2 | ||||||
| POST | /accounts/get | Retrieve the list of accounts on an Item, with cached balances. | read | Accounts | Current | |
Free to call; returns cached balances rather than a real-time check. Acts onaccount Permission (capability) AccountsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /accounts/balance/get | Retrieve real-time balances for an Item's accounts, fetched live from the institution. | read | Balance | Current | |
Gated by the Balance product, sold only alongside another product such as Auth or Transactions. Acts onbalance Permission (capability) BalanceVersionAvailable since the API’s base version Webhook eventNone Rate limit5/min, 30/hr per Item SourceOfficial documentation ↗ | ||||||
TransactionsMethods for reading transaction history and recurring streams.4 | ||||||
| POST | /transactions/sync | Retrieve added, modified, and removed transactions since a cursor, the recommended sync model. | read | Transactions | Current | |
Cursor-based; pair with the SYNC_UPDATES_AVAILABLE webhook to fetch only on change. Acts ontransaction Permission (capability) TransactionsVersionAvailable since the API’s base version Webhook event transactions-sync-updates-availableRate limit50/min per Item SourceOfficial documentation ↗ | ||||||
| POST | /transactions/get | Fetch transactions for an account over a date range, the legacy offset-paginated method. | read | Transactions | Current | |
Superseded by /transactions/sync for new integrations. Acts ontransaction Permission (capability) TransactionsVersionAvailable since the API’s base version Webhook eventNone Rate limit30/min per Item SourceOfficial documentation ↗ | ||||||
| POST | /transactions/recurring/get | Return recurring transaction streams identified on an Item, like subscriptions and regular bills. | read | Transactions | Current | |
Read-only. Acts onrecurring_transaction Permission (capability) TransactionsVersionAvailable since the API’s base version Webhook event transactions-recurring-updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /transactions/refresh | Force an on-demand check for new transaction data instead of waiting for the scheduled update. | write | Transactions | Current | |
An on-demand refresh that is billed separately and tightly rate-limited. Acts ontransaction Permission (capability) TransactionsVersionAvailable since the API’s base version Webhook eventNone Rate limit2/min, 120/hr, 2,880/day per Item SourceOfficial documentation ↗ | ||||||
AuthMethods for reading bank account and routing numbers for money movement.1 | ||||||
| POST | /auth/get | Retrieve bank account and routing numbers for an Item's accounts, for setting up transfers. | read | Auth | Current | |
Gated by the Auth product; returns ACH, EFT, BACS, or IBAN numbers depending on region. Acts onaccount_numbers Permission (capability) AuthVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IdentityMethods for reading account-holder identity and matching it against supplied data.2 | ||||||
| POST | /identity/get | Retrieve account-holder identity on file, including names, emails, phone numbers, and addresses. | read | Identity | Current | |
Only name data is guaranteed; other fields come back empty if the institution does not provide them. Acts onowner Permission (capability) IdentityVersionAvailable since the API’s base version Webhook eventNone Rate limit15/min per Item SourceOfficial documentation ↗ | ||||||
| POST | /identity/match | Score how well supplied identity data matches the identity on file at the institution. | read | Identity | Current | |
Returns match scores from 0 to 100 for name, phone, email, and address. Acts onowner Permission (capability) IdentityVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InvestmentsMethods for reading investment holdings and investment transactions.3 | ||||||
| POST | /investments/holdings/get | Retrieve current investment holdings and the securities behind them for an Item. | read | Investments | Current | |
Read-only. Acts onholding Permission (capability) InvestmentsVersionAvailable since the API’s base version Webhook event holdings-default-updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /investments/transactions/get | Retrieve up to 24 months of investment transactions for an Item's investment accounts. | read | Investments | Current | |
Read-only; paginated and returned in reverse-chronological order. Acts oninvestment_transaction Permission (capability) InvestmentsVersionAvailable since the API’s base version Webhook event investments-transactions-default-updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /investments/refresh | Force an on-demand refresh of investment holdings and transactions for an Item. | write | Investments | Current | |
An on-demand refresh without requiring the user to re-authenticate. Acts oninvestment_transaction Permission (capability) InvestmentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LiabilitiesMethods for reading loan and credit-account liability data.1 | ||||||
| POST | /liabilities/get | Retrieve liability data for an Item, covering credit, mortgage, and student-loan accounts. | read | Liabilities | Current | |
Read-only; includes APRs, payment terms, and balances. Acts onliability Permission (capability) LiabilitiesVersionAvailable since the API’s base version Webhook event liabilities-default-updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IncomeMethods for creating a user and reading bank and payroll income.4 | ||||||
| POST | /user/create | Create a user_token that represents a person, so income sources can be associated with it. | write | Income | Current | |
Called before /link/token/create for Income, Plaid Check, Multi-Item Link, and Plaid Protect. Acts onuser Permission (capability) IncomeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /credit/bank_income/get | Return a bank income report derived from deposits across a user's connected accounts. | read | Income | Current | |
Read-only; analyzes deposits to identify income sources, amounts, and frequencies. Acts onbank_income Permission (capability) IncomeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /credit/payroll_income/get | Retrieve payroll income for a user, including paystubs and tax documents like W-2s and 1099s. | read | Income | Current | |
Read-only; sourced from connected payroll providers or uploaded documents. Acts onpayroll_income Permission (capability) IncomeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /credit/sessions/get | Retrieve metadata and results from a user's completed income-verification Link sessions. | read | Income | Current | |
Read-only. Acts onsession Permission (capability) IncomeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Plaid notifies an app when something changes on an Item or when an asynchronous job finishes, like new transactions being ready to fetch or an Item entering an error state. It sends a JSON body naming a webhook_type and webhook_code, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
TRANSACTIONS: SYNC_UPDATES_AVAILABLE | New transaction updates are ready to fetch through /transactions/sync. | /transactions/sync |
TRANSACTIONS: RECURRING_TRANSACTIONS_UPDATE | Recurring transaction streams on an Item have new updates. | /transactions/recurring/get |
HOLDINGS: DEFAULT_UPDATE | New or changed investment holdings are available to fetch. | /investments/holdings/get |
INVESTMENTS_TRANSACTIONS: DEFAULT_UPDATE | New investment transactions are available to fetch. | /investments/transactions/get |
LIABILITIES: DEFAULT_UPDATE | New or updated liabilities have been detected on a liabilities Item. | /liabilities/get |
ITEM: WEBHOOK_UPDATE_ACKNOWLEDGED | An Item's webhook URL was updated, confirmed at the new URL. | /item/webhook/update |
Plaid limits how often each endpoint can be called, both per connected Item and across the whole account, and the ceilings differ by endpoint.
Plaid limits each endpoint both per connected Item and across the whole account, and the ceilings differ by endpoint. Per Item, /transactions/sync allows 50 requests a minute, /transactions/get 30, /identity/get 15, /accounts/balance/get 5 a minute and 30 an hour, and the on-demand /transactions/refresh just 2 a minute, 120 an hour, and 2,880 a day; per account the ceilings run far higher, like 20,000 a minute for /transactions/get. Going over returns HTTP 429 with error_type RATE_LIMIT_EXCEEDED and an endpoint-specific code such as TRANSACTIONS_LIMIT or ACCOUNTS_LIMIT. Per-method ceilings are shown on each row.
Pagination depends on the product. /transactions/sync is cursor-based: it returns added, modified, and removed transactions plus a next_cursor and a has_more flag, and a caller keeps calling until has_more is false. Older endpoints like /transactions/get and /investments/transactions/get use offset and count over a date range. A request is capped by a per-call count, so large result sets are read across several pages.
A single /transactions/get or /investments/transactions/get call returns at most 500 transactions, set by the count parameter, with offset advancing through the rest. /transactions/sync caps each page at 500 by default through its count parameter. Investment transaction history reaches back up to 24 months.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_REQUEST | The request was malformed, for example a missing or unknown field or a structurally bad body. | Read error_message, fix the request shape, and resend. It is not retryable as-is. |
| 400 | INVALID_INPUT | The request was well-formed but a value was wrong, like a bad access_token or invalid credentials. | Correct the offending field, such as the access_token or client_id and secret, and resend. |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests hit a per-Item or per-client limit, with a specific code like TRANSACTIONS_LIMIT or ACCOUNTS_LIMIT. | Back off and retry with exponential backoff, and smooth the request rate per Item. |
| 400 | ITEM_ERROR | Something is wrong with the Item itself, for example ITEM_LOGIN_REQUIRED when stored credentials are no longer valid. | Send the user through Link's update mode to repair the Item before retrying. |
| 400 | INSTITUTION_ERROR | The financial institution is unavailable or returned an error, often a temporary outage on its side. | Treat as transient: retry later with backoff and surface a try-again message to the user. |
| 500 | API_ERROR | An internal error on Plaid's side, or planned maintenance. | Retry with backoff, and contact Plaid support if it persists. |
Plaid pins the API to a dated version through the Plaid-Version header, so a fixed date keeps response shapes stable until an integration chooses to move up.
The current dated API version, pinned with the Plaid-Version header. It removed public_key authentication, so calls authenticate with client_id and secret. It also stopped returning a removed boolean from /item/remove, made country_codes mandatory for institutions endpoints, and restructured /processor/auth/get to match /auth/get.
Expanded international support across Auth and Identity. Auth numbers grew to include BACS (UK) and international IBAN and BIC formats, Identity moved owner data onto each account and renamed fields for international use, and a country field was added to identity and transactions.
Restructured Auth account numbers to support both US ACH and Canadian EFT formats, and added currency-code fields to accounts and transactions.
The earliest dated API version, the baseline before the later international and authentication changes.
Pin a version with the Plaid-Version header and move up deliberately.
Plaid API changelog ↗Bollard AI sits between a team's AI agents and Plaid. Grant each agent exactly the access it needs, read or write, product by product, and every call is checked and logged.