plaid-python

plaid-python is the official Python SDK for Plaid, the API platform that lets applications connect to users’ bank accounts for authentication, transaction history, balances, identity verification, and income and asset data. The library is generated directly from Plaid’s published OpenAPI specification, so every request and response is represented as a strongly-typed model class rather than a hand-maintained wrapper, and it stays in lockstep with the hundreds of endpoints Plaid exposes across its product surface.

Developers use it to instantiate a PlaidApi client against Plaid’s Sandbox or Production environment, then call typed request objects such as TransactionsSyncRequest or AuthGetRequest to exchange public tokens for access tokens, pull linked-account data, and handle Plaid’s structured ApiException errors. Because the client ships hundreds of generated model classes covering the full breadth of Plaid’s Auth, Transactions, Identity, Liabilities, Investments, and Payment Initiation products, teams get compile-time-style safety around a financial API surface that changes monthly.

What You Get

• A PlaidApi client class with ~350 generated methods covering every documented Plaid endpoint
• Typed request and response model classes (e.g. TransactionsSyncRequest, AuthGetResponse) instead of raw dicts
• Built-in ApiException handling that surfaces Plaid’s structured error_code values
• A Configuration/Environment object for switching cleanly between Sandbox and Production
• to_dict() helpers on response models for easy JSON serialization
• Coverage of Plaid’s full product line: Auth, Transactions, Identity, Assets, Liabilities, Investments, Income, Payment Initiation, and Link token creation

Common Use Cases

• Exchanging a Link public_token for a persistent access_token after a user connects their bank
• Pulling categorized transaction history via the Transactions Sync endpoint for budgeting or lending apps
• Verifying account and routing numbers with the Auth product before initiating ACH transfers
• Running KYC-style identity verification against linked bank accounts
• Fetching downloadable Asset Reports for underwriting workflows
• Building fintech backends that need typed, versioned access to Plaid without maintaining a custom HTTP wrapper

Under The Hood

Architecture The library is a single generated plaid package built around three layers: plaid/api/plaid_api.py defines one PlaidApi class exposing roughly 350 endpoint methods; plaid/model/ and plaid/models/ hold thousands of generated request/response classes (ModelNormal/ModelComposed subclasses defined in model_utils.py) that validate and serialize field types; and plaid/api_client.py plus plaid/rest.py handle the actual HTTP transport over urllib3, including a thread pool for concurrent calls. plaid/configuration.py centralizes environment selection (Environment.Sandbox/Production) and API-key headers. Every endpoint method follows the same generated shape — build a typed request model, pass it to PlaidApi, get a typed response model back — so the abstraction that would break if changed is the OpenAPI Generator template itself (in templates/), not hand-written application logic.

Tech Stack Pure Python 3.6+ with a deliberately thin runtime dependency set: urllib3 for HTTP, python-dateutil for date parsing, and nulltype for representing OpenAPI’s distinct ‘unset’ vs ‘null’ semantics. Packaging uses classic setuptools/setup.py. Development tooling (declared in requirements.txt) includes pytest with pytest-xdist/pytest-cov for test execution, flake8 plus flake8-mutable for linting, coverage/cov-core for coverage reporting, and sphinx for docs generation; CI runs on CircleCI (.circleci/config.yml). A Dockerfile and Makefile support containerized local development.

Code Quality There are no unit tests for the generated model/client code itself — correctness of the generation is effectively delegated to Plaid’s upstream OpenAPI Generator pipeline. Instead, tests/integration/ contains an extensive suite of live-API integration tests, one file per product (Auth, Transactions, Identity, Liabilities, Investments, Payment Initiation, Income Verification, and more), that exercise real Sandbox endpoints end-to-end via a shared create_client() helper in tests/integration/util.py. Error handling is explicit and typed: HTTP and validation failures raise ApiException/ApiTypeError/ApiValueError from plaid/exceptions.py rather than being swallowed. Naming and structure are fully generator-driven and consistent across every model, though as auto-generated code there is no traditional hand-authored type design to critique.

API Design The developer experience favors explicitness over convenience: every call requires constructing a purpose-built request object (e.g. TransactionsSyncRequest) rather than passing loose keyword arguments, which adds boilerplate but makes the ~350-endpoint surface self-documenting and IDE-autocompletable. Response models expose a consistent .to_dict() for JSON serialization, and the README documents common patterns (creating an Item via Link, syncing transactions, handling ITEM_LOGIN_REQUIRED) directly rather than leaving them to be inferred from generated docstrings. The tradeoff is that onboarding requires learning the request/response model naming convention rather than reading loosely-typed JSON payloads, but that convention is applied with total consistency since it is machine-generated.