Plaid

Warnings

• breaking v8.0.0 (August 2021) completely removed the old Client class and all previous import patterns. Any tutorial using 'from plaid import Client' or 'Client(client_id=..., secret=..., environment=...)' fails with ImportError.
  Fix: Use Configuration + ApiClient + PlaidApi pattern. See README for current quickstart.
• breaking plaid-python ships a major version (x.0.0) roughly monthly. Major versions may include breaking changes — new required fields, renamed parameters, or removed endpoints. Unpinned installs will auto-upgrade.
  Fix: Pin to a specific version in production: pip install plaid-python==38.3.0. Monitor changelog before upgrading major versions.
• breaking Each endpoint requires importing its specific request model. Passing a plain dict instead of the typed request object raises a TypeError. Old-style dict-based calls from pre-v8 tutorials do not work.
  Fix: Import the model for each endpoint: from plaid.model.transactions_sync_request import TransactionsSyncRequest, then pass an instance.
• gotcha Sandbox and Production have separate API secrets. The client_id is shared but the secret differs per environment. Using the wrong secret for an environment returns 401.
  Fix: Get environment-specific secrets from Plaid Dashboard > Team Settings > Keys. Store separately as PLAID_SECRET_SANDBOX and PLAID_SECRET_PRODUCTION.
• gotcha Plaid API responses are typed objects, not dicts. Code trying to access response['transactions'] fails with TypeError. Attributes are accessed as response.added, response.modified, etc.
  Fix: Access typed attributes: response.added for new transactions, response.next_cursor for pagination cursor, etc.
• gotcha Beta product APIs (e.g. Assets, CRA) are subject to breaking changes without versioning, with 30 days notice. GA products are versioned but the SDK fixes to a single API version — there is no per-request API version override.
  Fix: Monitor Plaid changelog for beta product changes. For GA products, upgrade SDK major versions intentionally, not automatically.

Install

• pip install plaid-python Python

Imports

• PlaidApi

  import plaid
  from plaid.api import plaid_api
  
  configuration = plaid.Configuration(
      host=plaid.Environment.Sandbox,
      api_key={'clientId': CLIENT_ID, 'secret': SECRET}
  )
  api_client = plaid.ApiClient(configuration)
  client = plaid_api.PlaidApi(api_client)

  Old Client() class was removed in v8.0.0 (August 2021). All pre-v8 import patterns fail. The new pattern requires Configuration + ApiClient + PlaidApi.

Quickstart

Plaid uses strongly-typed request/response models. Each endpoint has its own request model (e.g. TransactionsSyncRequest). Import the specific model for each call.

import plaid
from plaid.api import plaid_api
from plaid.model.transactions_sync_request import TransactionsSyncRequest
import json

configuration = plaid.Configuration(
    host=plaid.Environment.Sandbox,  # or Production
    api_key={
        'clientId': 'your_client_id',
        'secret': 'your_secret'
    }
)
api_client = plaid.ApiClient(configuration)
client = plaid_api.PlaidApi(api_client)

# Sync transactions
request = TransactionsSyncRequest(access_token='access-sandbox-...')
response = client.transactions_sync(request)
transactions = response.added

# Error handling
try:
    response = client.transactions_sync(request)
except plaid.ApiException as e:
    error = json.loads(e.body)
    print(error['error_code'])  # e.g. 'ITEM_LOGIN_REQUIRED'