{"id":15759,"library":"plaid","title":"Plaid Node.js Client","description":"The `plaid` package is the official Node.js client library for interacting with the Plaid API, providing programmatic access to financial data. Currently at version 42.1.0, the library is actively maintained with updates typically released on a monthly basis, aligning with Plaid API developments. It is generated directly from Plaid's OpenAPI schema, ensuring comprehensive coverage of the latest API version (specifically `2020-09-14`). A key differentiator is its direct support for various Plaid environments (sandbox, development, production) and its use of semantic versioning, with major version increments indicating potentially breaking changes. This client simplifies authentication and API request handling, abstracting the underlying HTTP requests and providing TypeScript type definitions for robust development.","status":"active","version":"42.1.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/plaid/plaid-node","tags":["javascript","plaid","plaid.com","typescript"],"install":[{"cmd":"npm install plaid","lang":"bash","label":"npm"},{"cmd":"yarn add plaid","lang":"bash","label":"yarn"},{"cmd":"pnpm add plaid","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses named exports and is designed for ESM. CommonJS 'require' syntax will not work as expected with modern versions.","wrong":"const Configuration = require('plaid').Configuration;","symbol":"Configuration","correct":"import { Configuration } from 'plaid';"},{"note":"PlaidApi is a named export, not a default export. Ensure you destructure it correctly.","wrong":"import PlaidApi from 'plaid';","symbol":"PlaidApi","correct":"import { PlaidApi } from 'plaid';"},{"note":"Used to select the target Plaid environment (e.g., sandbox, production). Like other core components, it's a named export and benefits from TypeScript typing.","wrong":"const PlaidEnvironments = require('plaid').PlaidEnvironments;","symbol":"PlaidEnvironments","correct":"import { PlaidEnvironments } from 'plaid';"}],"quickstart":{"code":"import { Configuration, PlaidApi, PlaidEnvironments, Products, CountryCode } from 'plaid';\n\n// Replace with your actual Plaid API credentials. Consider using environment variables.\nconst CLIENT_ID = process.env.PLAID_CLIENT_ID ?? 'your_client_id';\nconst SECRET = process.env.PLAID_SECRET ?? 'your_secret';\n\n// Configure the Plaid client\nconst configuration = new Configuration({\n  basePath: PlaidEnvironments.sandbox, // Or PlaidEnvironments.production for live data\n  baseOptions: {\n    headers: {\n      'PLAID-CLIENT-ID': CLIENT_ID,\n      'PLAID-SECRET': SECRET,\n      'Plaid-Version': '2020-09-14', // Recommended to explicitly set the API version\n    },\n  },\n});\n\nconst plaidClient = new PlaidApi(configuration);\n\nasync function getPlaidInstitutions() {\n  try {\n    // Define a request to fetch some institutions\n    const request = {\n      country_codes: [CountryCode.Us],\n      products: [Products.Auth],\n      count: 5,\n      offset: 0,\n    };\n    const response = await plaidClient.institutionsGet(request);\n    console.log('Successfully fetched top 5 Institutions:');\n    response.data.institutions.forEach(inst => console.log(`- ${inst.name} (ID: ${inst.institution_id})`));\n    return response.data.institutions;\n  } catch (error: any) {\n    if (error.response) {\n      // Log only necessary parts to avoid exposing secrets in error.response.config.headers\n      console.error('Plaid API Error:', error.response.data);\n    } else {\n      console.error('Plaid Client Error:', error.message);\n    }\n    throw error;\n  }\n}\n\n// Run the example\nPlaidEnvironments.sandbox === configuration.basePath ?\n  getPlaidInstitutions().then(() => console.log('\\nExample complete using Sandbox environment.')) :\n  console.warn('Warning: Not running institution fetch in non-sandbox environment for quickstart.');\n","lang":"typescript","description":"This quickstart demonstrates how to initialize the Plaid client with API credentials and environment, then fetch a list of top institutions using the `institutionsGet` endpoint. It includes basic error handling and best practices for environment variables and API versioning."},"warnings":[{"fix":"Review the official Plaid client library changelog on GitHub and the API upgrade guide for specific migration instructions for your target version. Pay close attention to changes in model imports, enum usage, and request/response structures.","message":"Major version bumps of the `plaid-node` client library (e.g., from v8 to v9, or v9 to v42) often introduce breaking changes. Version 9.0.0, released in August 2021, represented a significant interface change due to the transition to an OpenAPI spec-generated client. Always consult the client library changelog and migration guide when upgrading major versions.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Always ensure your client library is updated to a recent version. Explicitly include `'Plaid-Version': '2020-09-14'` in your request headers via `baseOptions` during `Configuration` initialization to guarantee API version compatibility.","message":"The `plaid-node` client library is explicitly designed to support the `2020-09-14` Plaid API version. Using an outdated client library or implicitly relying on an older API version can lead to unexpected behavior or missing features.","severity":"gotcha","affected_versions":"<42.0.0"},{"fix":"Only log specific parts of the error object, such as `error.response.data` for API-specific error details, and avoid logging `error.response.config.headers` or the entire `error` object.","message":"When handling errors, logging the full error object directly (e.g., `console.error(error)`) can expose sensitive API keys and secrets embedded in `error.response.config.headers`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all date and datetime strings sent in API requests precisely match the specified `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ssZ` (ISO 8601) formats, including the 'Z' for UTC if applicable. For TypeScript, consider using helper functions or libraries to ensure correct formatting.","message":"Dates and datetimes in Plaid API requests have strict string formatting requirements. `format: date` requires `'YYYY-MM-DD'` and `format: date-time` requires `'YYYY-MM-DDTHH:mm:ssZ'`. Failing to adhere to these formats or omitting time zone information for datetimes will result in an API error.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify that your `PLAID_CLIENT_ID` and `PLAID_SECRET` environment variables (or hardcoded values during development) exactly match your credentials from the Plaid Dashboard for the chosen environment (Sandbox, Development, or Production).","cause":"The Plaid API client was initialized with incorrect or missing `PLAID-CLIENT-ID` or `PLAID-SECRET` headers.","error":"Plaid API Error: { \"error_code\": \"INVALID_CREDENTIALS\", \"error_message\": \"client_id or secret is invalid\", ... }"},{"fix":"Switch to ES Module `import` statements: `import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';`. If you must use CommonJS, ensure your environment supports it correctly, or investigate if an older version of the library explicitly supported CommonJS exports.","cause":"Attempting to use CommonJS `require()` syntax with a library that is primarily designed for ES Modules (ESM) and uses named exports, especially in a modern Node.js project where `type: \"module\"` is set in `package.json`.","error":"TypeError: Cannot read properties of undefined (reading 'Configuration') OR PlaidApi is not a constructor"},{"fix":"Review the specific endpoint documentation for the correct date format. Ensure all date parameters are formatted as `YYYY-MM-DD` strings. For datetimes, use `YYYY-MM-DDTHH:mm:ssZ`.","cause":"A date field in an API request (e.g., `start_date`, `end_date` for transactions) was not provided in the required `YYYY-MM-DD` string format.","error":"Plaid API Error: { \"error_code\": \"INVALID_INPUT\", \"error_message\": \"'start_date' must be in the format 'YYYY-MM-DD'\", ... }"}],"ecosystem":"npm"}